diff --git a/.github/workflows/release-tasks.yml b/.github/workflows/release-tasks.yml --- a/.github/workflows/release-tasks.yml +++ b/.github/workflows/release-tasks.yml @@ -26,7 +26,7 @@ doxygen \ graphviz \ python3-github \ - python3-recommonmark \ + python3-myst-parser \ python3-sphinx \ ninja-build \ texlive-font-utils diff --git a/clang/docs/conf.py b/clang/docs/conf.py --- a/clang/docs/conf.py +++ b/clang/docs/conf.py @@ -38,7 +38,7 @@ } try: - import recommonmark + import myst_parser except ImportError: # manpages do not use any .md sources if not tags.has('builder-man'): @@ -47,9 +47,9 @@ import sphinx if sphinx.version_info >= (3, 0): # This requires 0.5 or later. - extensions.append('recommonmark') + extensions.append('myst_parser') else: - source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} + source_parsers = {'.md': 'myst_parser.parsers.sphinx_.MystParser'} source_suffix['.md'] = 'markdown' # The encoding of source files. diff --git a/flang/docs/ComplexOperations.md b/flang/docs/ComplexOperations.md --- a/flang/docs/ComplexOperations.md +++ b/flang/docs/ComplexOperations.md @@ -34,7 +34,7 @@ ``` **FIR** -```c +``` func.func @_QPpow_self(%arg0: !fir.ref>) -> !fir.complex<4> { %0 = fir.alloca !fir.complex<4> %1 = fir.load %arg0 : !fir.ref> diff --git a/flang/docs/DiagnosticsReference.md b/flang/docs/DiagnosticsReference.md new file mode 100644 --- /dev/null +++ b/flang/docs/DiagnosticsReference.md @@ -0,0 +1 @@ +% This file intentionally left blank. Silences a warning about a missing reference from the automatically generated FlangCommandLineReference.rst diff --git a/flang/docs/FIRArrayOperations.md b/flang/docs/FIRArrayOperations.md --- a/flang/docs/FIRArrayOperations.md +++ b/flang/docs/FIRArrayOperations.md @@ -82,7 +82,7 @@ value while applying a runtime shape, shift, or slice to the memory reference, and its semantics guarantee immutability. -```mlir +``` %s = fir.shape_shift %lb1, %ex1, %lb2, %ex2 : (index, index, index, index) -> !fir.shapeshift<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shapeshift<2>) -> !fir.array @@ -103,7 +103,7 @@ One can use `fir.array_merge_store` to merge/copy the value of `a` in an array expression as shown above. -```mlir +``` %v = fir.array_load %a(%shape) : ... %r = fir.array_update %v, %f, %i, %j : (!fir.array, f32, index, index) -> !fir.array fir.array_merge_store %v, %r to %a : !fir.ref> @@ -136,7 +136,7 @@ an array expression as shown above. It can also be used to extract the element `a(r,s+1)` in the second expression. -```mlir +``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<2>) -> !fir.array @@ -164,7 +164,7 @@ One can use `fir.array_update` to update the (implied) value of `a(i,j)` in an array expression as shown above. -```mlir +``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<2>) -> !fir.array @@ -205,7 +205,7 @@ be used to recover the reference element `a(r,s+1)` in the second expression. -```mlir +``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<2>) -> !fir.array @@ -275,7 +275,7 @@ that is used to merge the final result back with an `array_merge_store` operation. -```mlir +``` // fetch the value of one of the array value's elements %1 = fir.array_access %v, %i, %j : (!fir.array, index, index) -> !fir.ref // modify the element by storing data using %1 as a reference diff --git a/flang/docs/FlangDriver.md b/flang/docs/FlangDriver.md --- a/flang/docs/FlangDriver.md +++ b/flang/docs/FlangDriver.md @@ -60,7 +60,7 @@ frontend specific flag from the _compiler_ directly to the _frontend_ driver, e.g.: -```lang=bash +```bash flang-new -Xflang -fdebug-dump-parse-tree input.f95 ``` @@ -68,7 +68,7 @@ -fc1`. Without the forwarding flag, `-Xflang`, you would see the following warning: -```lang=bash +```bash flang-new: warning: argument unused during compilation: ``` diff --git a/flang/docs/HighLevelFIR.md b/flang/docs/HighLevelFIR.md --- a/flang/docs/HighLevelFIR.md +++ b/flang/docs/HighLevelFIR.md @@ -987,7 +987,7 @@ Lowering output: -```HLFIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} : !fir.box>, !fir.box> %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.box> @@ -1001,7 +1001,7 @@ associated variables that are neither target nor pointers. - Lower to assignment to loop: -```HFLIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} : !fir.box>, !fir.box> %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.box> @@ -1073,7 +1073,7 @@ Lowering output: -```HLFIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>, %arg2: !fir.box>>, %arg3: !fir.ref>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box, !fir.box %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.box> @@ -1111,7 +1111,7 @@ second one at the hlfir.apply. -```HLFIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>, %arg2: !fir.box>>, %arg3: !fir.ref>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box, !fir.box %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.box> @@ -1156,7 +1156,7 @@ %add hlfir.elemental. -```HLFIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>, %arg2: !fir.box>>, %arg3: !fir.ref>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box, !fir.box %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.box> @@ -1195,7 +1195,7 @@ Step 4: Lower assignments to regular loops since they have the no_overlap attribute, and inline the hlfir.elemental into the first loop nest. -```HLFIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>, %arg2: !fir.box>>, %arg3: !fir.ref>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} {fir.target} : !fir.box, !fir.box %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.box> @@ -1241,7 +1241,7 @@ conformance checks can be added for %a, %b and %p. - %temp is small, and its fir.allocmem can be promoted to a stack allocation -```HLFIR +``` func.func @_QPfoo(%arg0: !fir.box>, %arg1: !fir.box>, %arg2: !fir.box>>, %arg3: !fir.ref>) { // ..... %cshape = fir.shape %c100 @@ -1286,7 +1286,7 @@ input IO) by inlining the elemental body into the created loops, and identifying the hlfir.designate producing the result. -```HFLFIR +``` func.func @_QPfoo(%arg0: !fir.ref>, %arg1: !fir.ref>, %arg2: !fir.box<>) { %a = hlfir.declare %arg0 {fir.def = "_QPfooEa"} : !fir.box>, !fir.ref> %b = hlfir.declare %arg1 {fir.def = "_QPfooEb"} : !fir.box>, !fir.ref> diff --git a/flang/docs/OptionComparison.md b/flang/docs/OptionComparison.md --- a/flang/docs/OptionComparison.md +++ b/flang/docs/OptionComparison.md @@ -8,7 +8,7 @@ # Compiler options comparison -This document catalogs the options processed by F18's peers/competitors. Much of the document is taken up by a set of tables that list the options categorized into different topics. Some of the table headings link to more information about the contents of the tables. For example, the table on **Standards conformance** options links to [notes on Standards conformance](#standards). +This document catalogs the options processed by F18's peers/competitors. Much of the document is taken up by a set of tables that list the options categorized into different topics. Some of the table headings link to more information about the contents of the tables. For example, the table on **Standards conformance** options links to [notes on Standards conformance](standards). **There's also important information in the ___[Appendix section](#appendix)___ near the end of the document on how this data was gathered and what ___is___ and ___is not___ included in this document.** @@ -1187,7 +1187,8 @@ ## Notes -**Standards conformance:** +(standards)= +**Standards conformance:** All conformance options are similar -- they issue warnings if non-standard features are used. All defaults are to allow extensions without warnings. The GNU, IBM, and Intel compilers allow multiple standard levels to be specified. diff --git a/flang/docs/ParameterizedDerivedTypes.md b/flang/docs/ParameterizedDerivedTypes.md --- a/flang/docs/ParameterizedDerivedTypes.md +++ b/flang/docs/ParameterizedDerivedTypes.md @@ -266,7 +266,7 @@ function. **FIR** -```c +``` // Example of compiler generated functions to compute offsets, size, etc. // This is just an example and actual implementation might have more functions. @@ -337,7 +337,7 @@ ``` Example of offset computation in the PDTs. -```c +``` %0 = call @_len_type3.field.typeparam.1(%i, %j) : (index, index) -> index %1 = call @_len_type3.field.typeparam.2(%i, %j) : (index, index) -> index %2 = call @_len_type3.offset.fld(%i, %j) : (index, index) -> index @@ -367,7 +367,7 @@ computation. **FIR** -```c +``` %5 = fir.field_index i, !fir.type<_QMmod1Tt{l:i32,i:!fir.array}>(%n : i32) ``` @@ -394,8 +394,8 @@ type t1(n, m) integer, len :: n = 2 integer, len :: m = 4 - integer, len :: _t1_n_m = 8 ! hidden extra length type parameter - real :: data(_t1_n_m) + integer, len :: t1_n_m = 8 ! hidden extra length type parameter + real :: data(t1_n_m) end type ``` @@ -431,7 +431,7 @@ ``` **FIR** -```c +``` // For allocatable %5 = fir.call @_FortranAAllocatableInitDerived(%desc, %type) : (!fir.box, ) -> () // The AllocatableSetDerivedLength functions is called for each length type parameters. @@ -456,7 +456,7 @@ ``` **FIR** -```c +``` // For allocatable %8 = fir.call @_FortranAAllocatableDeallocate(%desc1) : (!fir.box) -> (i32) @@ -475,7 +475,7 @@ ``` **FIR** -```c +``` %0 = fir.call @_FortranAPointerNullifyDerived(%desc, %type) : (!fir.box, !fir.tdesc) -> () ``` @@ -507,7 +507,7 @@ ``` **FIR** -```c +``` func.func @_QMpdtPprint_pdt() { %l = arith.constant = 10 %0 = fir.alloca !fir.type<_QMpdtTt{l:i32,i:!fir.array}> (%l : i32) {bindc_name = "x", uniq_name = "_QMpdt_initFlocalEx"} @@ -832,7 +832,7 @@ operation so its size can be computed accordingly. **FIR** -```c +``` %i = arith.constant 10 : i32 %0 = fir.alloca !fir.type<_QMmod1Tpdt{i:i32,data:!fir.array}> (%i : i32) // %i is the ssa value of the length type parameter @@ -845,7 +845,7 @@ passed so the size can be computed accordingly. **FIR** -```c +``` %i = arith.constant 10 : i32 %0 = fir.alloca !fir.type<_QMmod1Tpdt{i:i32,data:!fir.array}> (%i : i32) // ... @@ -866,7 +866,7 @@ ``` **FIR** -```c +``` func.func @_QMpdt_initPlocal() { %c2_i32 = arith.constant 2 : i32 %0 = fir.alloca !fir.type<_QMpdt_initTt{l:i32,i:!fir.array}> (%c2 : i32) @@ -892,7 +892,7 @@ values with a PDT so it can compute a correct offset. **FIR** -```c +``` %l = arith.constant 10 : i32 %1 = fir.field_index i, !fir.type<_QMpdt_initTt{l:i32,i:i32}> (%l : i32) %2 = fir.coordinate_of %ref, %1 : (!fir.type<_QMpdt_initTt{l:i32,i:i32}>, !fir.field) -> !fir.ref @@ -905,7 +905,7 @@ This operation is used to get the length type parameter offset in from a PDT. **FIR** -```c +``` func.func @_QPpdt_len_value(%arg0: !fir.box}>>) -> i32 { %0 = fir.len_param_index l, !fir.box}>> %1 = fir.coordinate_of %arg0, %0 : (!fir.box}>>, !fir.len) -> !fir.ref @@ -921,7 +921,7 @@ parameters is passed if the PDT is not boxed. **FIR** -```c +``` func.func @return_pdt(%buffer: !fir.ref>) { %l1 = arith.constant 3 : i32 %l2 = arith.constant 5 : i32 @@ -938,7 +938,7 @@ FIR. **FIR** -```c +``` // Operation used with a boxed PDT does not need the length type parameters as // they are directly retrieved from the box. %0 = fir.array_coor %boxed_pdt, %i, %j (fir.box}>>>>, index, index) -> !fir.ref}>>> diff --git a/flang/docs/PolymorphicEntities.md b/flang/docs/PolymorphicEntities.md --- a/flang/docs/PolymorphicEntities.md +++ b/flang/docs/PolymorphicEntities.md @@ -77,7 +77,7 @@ ``` **FIR** -```c +``` func.func @foo(%p : !fir.class>) ``` @@ -95,7 +95,7 @@ ``` **FIR** -```c +``` func.func @bar(%x : !fir.class) ``` @@ -413,7 +413,7 @@ ``` **FIR** -```c +``` %1 = fir.convert %0 : !fir.ref,base:f32,height:f32>>> %2 = fir.dispatch "get_area"(%1 : !fir.class,base:f32,height:f32>>) -> f32 ``` @@ -427,7 +427,7 @@ **LLVMIR** Representation of the derived type information with the bindings. -```c +``` %_QM__fortran_type_infoTderivedtype = type { { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8 }, i64, { ptr, i64, i32, i8, i8, i8, i8, ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, { ptr, i64, i32, i8, i8, i8, i8, [1 x [3 x i64]], ptr, [1 x i64] }, i32, i8, i8, i8, i8, [4 x i8] } %_QM__fortran_type_infoTbinding = type { %_QM__fortran_builtinsT__builtin_c_funptr, { ptr, i64, i32, i8, i8, i8, i8 } } %_QM__fortran_builtinsT__builtin_c_funptr = type { i64 } @@ -438,7 +438,7 @@ what it can look like in pseudo LLVM IR code. **LLVMIR** -```c +``` // Retrieve the bindings (vtable) from the type information from the descriptor %1 = call %_QM__fortran_type_infoTbinding* @_FortranAGetBindings(%desc) // Retrieve the position of the specific bindings in the table @@ -482,7 +482,7 @@ 2) Dummy argument is polymorphic and actual argument is fixed type. In these cases, the actual argument need to be boxed to be passed to the subroutine/function since those are expecting a descriptor. - ```c + ``` func.func @_QMmod1Ps(%arg0: !fir.class>) func.func @_QQmain() { %0 = fir.alloca !fir.type<_QMmod1Tshape{x:i32,y:i32}> {uniq_name = "_QFEsh"} @@ -550,7 +550,7 @@ ``` **FIR** -```c +``` %5 = fir.call @_FortranAioBeginUnformattedOutput(%c10_i32, %4, %c56_i32) : (i32, !fir.ref, i32) -> !fir.ref %6 = fir.embox %2 : (!fir.ref>) -> !fir.class> %7 = fir.convert %6 : (!fir.class>) -> !fir.box @@ -574,7 +574,7 @@ (`flang/include/flang/Runtime/derived-api.h`). **FIR** -```c +``` %5 = fir.call @_FortranADestroy(%desc) : (!fir.box) -> none ``` @@ -637,7 +637,7 @@ **FIR** The call to `get_area` in the `type is (triangle)` guard can be replaced. -```c +``` %3 = fir.dispatch "get_area"(%desc) // Replaced by %3 = fir.call @get_area_triangle(%desc) @@ -682,7 +682,7 @@ ``` **FIR** -```c +``` %0 = fir.address_of(@_QMgeometryE.dt.triangle) : !fir.ref> %1 = fir.convert %item1 : (!fir.ref,base:f32,height:f32>>>) -> !fir.ref> %2 = fir.call @_FortranAAllocatableInitDerived(%1, %0) @@ -708,7 +708,7 @@ ``` **FIR** -```c +``` %8 = fir.call @_FortranAAllocatableDeallocate(%desc1) %9 = fir.call @_FortranAAllocatableDeallocate(%desc2) ``` @@ -815,7 +815,7 @@ dynamic type of `a` must be copied when it is associated on `b`. **FIR** - ```c + ``` // fir.load must copy the dynamic type from the pointer `a` %0 = fir.address_of(@_QMmod1Ea) : !fir.ref>>> %1 = fir.load %0 : !fir.ref>>> diff --git a/flang/docs/PullRequestChecklist.md b/flang/docs/PullRequestChecklist.md --- a/flang/docs/PullRequestChecklist.md +++ b/flang/docs/PullRequestChecklist.md @@ -36,7 +36,7 @@ clang-format will do this for most code. But you may need to break up long strings. * Review declarations for proper use of `constexpr` and `const`. -* Follow the C++ [naming guidelines](C++style.html#naming) +* Follow the C++ [naming guidelines](C++style.md#naming) * Ensure that the names evoke their purpose and are consistent with existing code. * Used braced initializers. * Review pointer and reference types to make sure that you're using them diff --git a/flang/docs/conf.py b/flang/docs/conf.py --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -11,7 +11,6 @@ import sys, os from datetime import date -from recommonmark.parser import CommonMarkParser # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -20,12 +19,6 @@ # -- General configuration ----------------------------------------------------- -# https://github.com/readthedocs/recommonmark/issues/177 -#Method used to remove the warning message. -class CustomCommonMarkParser(CommonMarkParser): - def visit_document(self, node): - pass - # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' @@ -41,7 +34,7 @@ '.rst': 'restructuredtext', } try: - import recommonmark + import myst_parser except ImportError: # manpages do not use any .md sources if not tags.has('builder-man'): @@ -50,12 +43,18 @@ import sphinx if sphinx.version_info >= (3, 0): # This requires 0.5 or later. - extensions.append('recommonmark') + extensions.append('myst_parser') else: - source_parsers = {'.md': CustomCommonMarkParser} + source_parsers = {'.md': 'myst_parser.parsers.sphinx_.MystParser'} source_suffix['.md'] = 'markdown' + + myst_heading_anchors = 7 + extensions.append('sphinx_markdown_tables') + # Don't warn about markdown headers going from h1 -> h3 + suppress_warnings = ['myst.header'] + # Setup AutoStructify for inline .rst toctrees in index.md from recommonmark.transform import AutoStructify @@ -70,11 +69,6 @@ DummyStateMachine.run_role = run_role def setup(app): - # Disable inline math to avoid - # https://github.com/readthedocs/recommonmark/issues/120 in Extensions.md - app.add_config_value('recommonmark_config', { - 'enable_inline_math': False - }, True) app.add_transform(AutoStructify) # The encoding of source files. diff --git a/flang/docs/index.md b/flang/docs/index.md --- a/flang/docs/index.md +++ b/flang/docs/index.md @@ -36,19 +36,26 @@ .. toctree:: :titlesonly: + Aliasing + AliasingAnalysisFIR ArrayComposition BijectiveInternalNameUniquing Calls Character + ComplexOperations ControlFlowGraph + DesignGuideline Directives DoConcurrent Extensions + FIRArrayOperations FIRLangRef FlangCommandLineReference FlangDriver + FortranFeatureHistory FortranIR FortranLLVMTestSuite + HighLevelFIR IORuntimeInternals Intrinsics IntrinsicTypes @@ -58,9 +65,12 @@ OpenMP-semantics OptionComparison Overview + ParameterizedDerivedTypes ParserCombinators Parsing + PolymorphicEntities Preprocessing + ProcedurePointer RuntimeDescriptor RuntimeTypeInfo Semantics @@ -74,3 +84,11 @@ * :ref:`modindex` * :ref:`search` ``` + +```eval_rst +.. toctree:: + :hidden: + + FIR/FIRLangRef_Header + DiagnosticsReference +``` diff --git a/flang/include/flang/Optimizer/Dialect/FIROps.td b/flang/include/flang/Optimizer/Dialect/FIROps.td --- a/flang/include/flang/Optimizer/Dialect/FIROps.td +++ b/flang/include/flang/Optimizer/Dialect/FIROps.td @@ -73,7 +73,7 @@ an optional name. The allocation may have a dynamic repetition count for allocating a sequence of locations for the specified type. - ```mlir + ``` %c = ... : i64 %x = fir.alloca i32 %y = fir.alloca !fir.array<8 x i64> @@ -192,7 +192,7 @@ The memory object is in an undefined state. `allocmem` operations must be paired with `freemem` operations to avoid memory leaks. - ```mlir + ``` %0 = fir.allocmem !fir.array<10 x f32> fir.freemem %0 : !fir.heap> ``` @@ -246,7 +246,7 @@ in the undefined state as undefined behavior. This includes aliasing references, such as the result of an `fir.embox`. - ```mlir + ``` %21 = fir.allocmem !fir.type ... fir.freemem %21 : !fir.heap> @@ -265,7 +265,7 @@ Produces an immutable ssa-value of the referent type. A memory reference has type `!fir.ref`, `!fir.heap`, or `!fir.ptr`. - ```mlir + ``` %a = fir.alloca i32 %l = fir.load %a : !fir.ref ``` @@ -293,7 +293,7 @@ value must be of the same type as the referent type of the memory reference. - ```mlir + ``` %v = ... : f64 %p = ... : !fir.ptr fir.store %v to %p : !fir.ptr @@ -337,7 +337,7 @@ The fir.save_result associated to a function call must immediately follow the call and be in the same block. - ```mlir + ``` %buffer = fir.alloca fir.array, %c100 %shape = fir.shape %c100 %array_result = fir.call @foo() : () -> fir.array @@ -378,7 +378,7 @@ The number of code points copied is specified explicitly as the second argument. The length of the !fir.char type is ignored. - ```mlir + ``` fir.char_convert %1 for %2 to %3 : !fir.ref>, i32, !fir.ref> ``` @@ -410,7 +410,7 @@ This operation is typically created internally by the mem2reg conversion pass. An undefined value can be of any type except `!fir.ref`. - ```mlir + ``` %a = fir.undefined !fir.array<10 x !fir.type> ``` @@ -432,7 +432,7 @@ Constructs an ssa-value of the specified type with a value of zero for all bits. - ```mlir + ``` %a = fir.zero_bits !fir.box>> ``` @@ -563,7 +563,7 @@ at least one basic block with a corresponding `unit` match, and that block will be selected when all other conditions fail to match. - ```mlir + ``` fir.select %arg:i32 [1, ^bb1(%0 : i32), 2, ^bb2(%2,%arg,%arg2 : i32,i32,i32), -3, ^bb3(%arg2,%2 : i32,i32), @@ -586,7 +586,7 @@ same as `select`, but `select_rank` determines the rank of the selector variable at runtime to determine the best match. - ```mlir + ``` fir.select_rank %arg:i32 [1, ^bb1(%0 : i32), 2, ^bb2(%2,%arg,%arg2 : i32,i32,i32), 3, ^bb3(%arg2,%2 : i32,i32), @@ -608,7 +608,7 @@ the same as `select`, but `select_case` allows for the expression of more complex match conditions. - ```mlir + ``` fir.select_case %arg : i32 [ #fir.point, %0, ^bb1(%0 : i32), #fir.lower, %1, ^bb2(%2,%arg,%arg2,%1 : i32,i32,i32,i32), @@ -651,7 +651,7 @@ same as `select`, but `select_type` determines the type of the selector variable at runtime to determine the best match. - ```mlir + ``` fir.select_type %arg : !fir.box<()> [ #fir.type_is>, ^bb1(%0 : i32), #fir.type_is>, ^bb2(%2 : i32), @@ -684,7 +684,7 @@ program, for example. This instruction corresponds to the LLVM IR instruction `unreachable`. - ```mlir + ``` fir.unreachable ``` }]; @@ -709,7 +709,7 @@ let description = [{ The terminator for a GlobalOp with a body. - ```mlir + ``` global @variable : tuple { %0 = arith.constant 45 : i32 %1 = arith.constant 100.0 : f32 @@ -741,7 +741,7 @@ auxiliary information is packaged and abstracted as a value with box type by the calling routine. (In Fortran, these are called descriptors.) - ```mlir + ``` %c1 = arith.constant 1 : index %c10 = arith.constant 10 : index %5 = ... : !fir.ref> @@ -824,7 +824,7 @@ where x is described by a fir.box and has non default lower bounds, and then applying a new 2-dimension shape to this fir.box. - ```mlir + ``` %0 = fir.slice %c10, %c33, %c2 : (index, index, index) -> !fir.slice<1> %1 = fir.shift %c0 : (index) -> !fir.shift<1> %2 = fir.rebox %x(%1) [%0] : (!fir.box>, !fir.shift<1>, !fir.slice<1>) -> !fir.box> @@ -861,7 +861,7 @@ ```fortran CHARACTER(LEN=10) :: var ``` - ```mlir + ``` %4 = ... : !fir.ref>> %5 = arith.constant 10 : i32 %6 = fir.emboxchar %4, %5 : (!fir.ref>>, i32) -> !fir.boxchar<1> @@ -891,7 +891,7 @@ internal procedure or the internal procedure does not need a host context then the form takes only the procedure's symbol. - ```mlir + ``` %f = ... : (i32) -> i32 %0 = fir.emboxproc %f : ((i32) -> i32) -> !fir.boxproc<(i32) -> i32> ``` @@ -902,7 +902,7 @@ context's values accordingly, up to and including inhibiting register promotion of local values. - ```mlir + ``` %4 = ... : !fir.ref, !fir.ref>> %g = ... : (i32) -> i32 %5 = fir.emboxproc %g, %4 : ((i32) -> i32, !fir.ref, !fir.ref>>) -> !fir.boxproc<(i32) -> i32> @@ -927,7 +927,7 @@ Unboxes a value of `boxchar` type into a pair consisting of a memory reference to the CHARACTER data and the LEN type parameter. - ```mlir + ``` %45 = ... : !fir.boxchar<1> %46:2 = fir.unboxchar %45 : (!fir.boxchar<1>) -> (!fir.ref>, i32) ``` @@ -945,7 +945,7 @@ Unboxes a value of `boxproc` type into a pair consisting of a procedure pointer and a pointer to a host context. - ```mlir + ``` %47 = ... : !fir.boxproc<() -> i32> %48:2 = fir.unboxproc %47 : (!fir.ref<() -> i32>, !fir.ref>) ``` @@ -967,7 +967,7 @@ cases, respectively, is the address of the data, the address of the `CHARACTER` data, and the address of the procedure. - ```mlir + ``` %51 = fir.box_addr %box : (!fir.box) -> !fir.ref %52 = fir.box_addr %boxchar : (!fir.boxchar<1>) -> !fir.ref> %53 = fir.box_addr %boxproc : (!fir.boxproc) -> !P @@ -989,7 +989,7 @@ let description = [{ Extracts the LEN type parameter from a `boxchar` value. - ```mlir + ``` %45 = ... : !boxchar<1> // CHARACTER(20) %59 = fir.boxchar_len %45 : (!fir.boxchar<1>) -> i64 // len=20 ``` @@ -1011,7 +1011,7 @@ left to right from 0 to rank-1. This operation has undefined behavior if `dim` is out of bounds. - ```mlir + ``` %c1 = arith.constant 0 : i32 %52:3 = fir.box_dims %40, %c1 : (!fir.box>, i32) -> (index, index, index) ``` @@ -1044,7 +1044,7 @@ Returns the size of an element in an entity of `box` type. This size may not be known until runtime. - ```mlir + ``` %53 = fir.box_elesize %40 : (!fir.box) -> i32 // size=4 %54 = fir.box_elesize %40 : (!fir.box>) -> i32 ``` @@ -1065,7 +1065,7 @@ let description = [{ Returns the descriptor type code of an entity of `box` type. - ```mlir + ``` %1 = fir.box_typecode %0 : (!fir.box) -> i32 ``` }]; @@ -1083,7 +1083,7 @@ return true if the originating box value was from a `fir.embox` op with a mem-ref value that had the type !fir.heap. - ```mlir + ``` %r = ... : !fir.heap %b = fir.embox %r : (!fir.heap) -> !fir.box %a = fir.box_isalloc %b : (!fir.box) -> i1 // true @@ -1106,7 +1106,7 @@ true if the originating box value was from a fir.embox with a memory reference value that had the type !fir.array and/or a shape argument. - ```mlir + ``` %r = ... : !fir.ref %c_100 = arith.constant 100 : index %d = fir.shape %c_100 : (index) -> !fir.shape<1> @@ -1126,7 +1126,7 @@ let description = [{ Determine if the boxed value was from a POINTER entity. - ```mlir + ``` %p = ... : !fir.ptr %b = fir.embox %p : (!fir.ptr) -> !fir.box %a = fir.box_isptr %b : (!fir.box) -> i1 // true @@ -1144,7 +1144,7 @@ let description = [{ Extract the host context pointer from a boxproc value. - ```mlir + ``` %8 = ... : !fir.boxproc<(!fir.ref>) -> i32> %9 = fir.boxproc_host %8 : (!fir.boxproc<(!fir.ref>) -> i32>) -> !fir.ref> ``` @@ -1167,7 +1167,7 @@ Return the rank of a value of `box` type. If the value is scalar, the rank is 0. - ```mlir + ``` %57 = fir.box_rank %40 : (!fir.box>) -> i32 %58 = fir.box_rank %41 : (!fir.box) -> i32 ``` @@ -1190,7 +1190,7 @@ descriptor is an implementation defined value that fully describes a type to the Fortran runtime. - ```mlir + ``` %7 = fir.box_tdesc %41 : (!fir.box) -> !fir.tdesc ``` }]; @@ -1271,7 +1271,7 @@ value while applying a runtime shape, shift, or slice to the memory reference, and its semantics guarantee immutability. - ```mlir + ``` %s = fir.shape_shift %o, %n, %p, %m : (index, index, index, index) -> !fir.shapeshift<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shapeshift<2>) -> !fir.array @@ -1319,7 +1319,7 @@ an array expression as shown above. It can also be used to extract the element `a(r,s+1)` in the second expression. - ```mlir + ``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<2>) -> !fir.array @@ -1365,7 +1365,7 @@ One can use `fir.array_update` to update the (implied) value of `a(i,j)` in an array expression as shown above. - ```mlir + ``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<2>) -> !fir.array @@ -1419,7 +1419,7 @@ One can use `fir.array_modify` to update the (implied) value of `a(i)` in an array expression as shown above. - ```mlir + ``` %s = fir.shape %n : (index) -> !fir.shape<1> // Load the entire array 'a'. %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<1>) -> !fir.array @@ -1482,7 +1482,7 @@ be used to recover the reference element `a(r,s+1)` in the second expression. - ```mlir + ``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> // load the entire array 'a' %v = fir.array_load %a(%s) : (!fir.ref>, !fir.shape<2>) -> !fir.array @@ -1527,7 +1527,7 @@ log that is used to merge the final result back with an `array_merge_store` operation. - ```mlir + ``` // fetch the value of one of the array value's elements %1 = fir.array_access %v, %i, %j : (!fir.array, index, index) -> !fir.ref // modify the element by storing data using %1 as a reference @@ -1569,7 +1569,7 @@ One can use `fir.array_merge_store` to merge/copy the value of `a` in an array expression as shown above. - ```mlir + ``` %v = fir.array_load %a(%shape) : ... %r = fir.array_update %v, %f, %i, %j : (!fir.array, f32, index, index) -> !fir.array fir.array_merge_store %v, %r to %a : !fir.ref> @@ -1620,7 +1620,7 @@ One can use `fir.array_coor` to determine the address of `a(i,j)`. - ```mlir + ``` %s = fir.shape %n, %m : (index, index) -> !fir.shape<2> %1 = fir.array_coor %a(%s) %i, %j : (!fir.ref>, !fir.shape<2>, index, index) -> !fir.ref ``` @@ -1659,7 +1659,7 @@ Unlike LLVM's GEP instruction, one cannot stride over the outermost reference; therefore, the leading 0 index must be omitted. - ```mlir + ``` %i = ... : index %h = ... : !fir.heap> %p = fir.coordinate_of %h, %i : (!fir.heap>, index) -> !fir.ref @@ -1701,7 +1701,7 @@ Note that the entity ssa-value must be of compile-time known size in order to use this operation. - ```mlir + ``` %f = fir.field_index field, !fir.type %s = ... : !fir.type %v = fir.extract_value %s, %f : (!fir.type, !fir.field) -> i32 @@ -1729,7 +1729,7 @@ or `fir.insert_value` instructions to compute (abstract) addresses of subobjects. - ```mlir + ``` %f = fir.field_index field, !fir.type ``` }]; @@ -1764,7 +1764,7 @@ must be applied to a reified object, so all shape information must be specified. The extent must be nonnegative. - ```mlir + ``` %d = fir.shape %row_sz, %col_sz : (index, index) -> !fir.shape<2> ``` }]; @@ -1796,7 +1796,7 @@ be applied to a reified object, so all shifted shape information must be specified. The extent must be nonnegative. - ```mlir + ``` %d = fir.shape_shift %lo, %extent : (index, index) -> !fir.shapeshift<1> ``` }]; @@ -1843,7 +1843,7 @@ must be applied to a reified object, so all shift information must be specified. - ```mlir + ``` %d = fir.shift %row_lb, %col_lb : (index, index) -> !fir.shift<2> ``` }]; @@ -1872,7 +1872,7 @@ must be applied to a reified object, so all slice information must be specified. The extent must be nonnegative and the stride must not be zero. - ```mlir + ``` %d = fir.slice %lo, %hi, %step : (index, index, index) -> !fir.slice<1> ``` @@ -1880,7 +1880,7 @@ op can be given a component path (narrowing from the product type of the original array to the specific elemental type of the sliced projection). - ```mlir + ``` %fld = fir.field_index component, !fir.type %d = fir.slice %lo, %hi, %step path %fld : (index, index, index, !fir.field) -> !fir.slice<1> @@ -1889,7 +1889,7 @@ Projections of `!fir.char` type can be further narrowed to invariant substrings. - ```mlir + ``` %d = fir.slice %lo, %hi, %step substr %offset, %width : (index, index, index, index, index) -> !fir.slice<1> ``` @@ -1935,7 +1935,7 @@ Note that the entity ssa-value must be of compile-time known size in order to use this operation. - ```mlir + ``` %a = ... : !fir.array<10xtuple> %f = ... : f32 %o = ... : i32 @@ -1965,7 +1965,7 @@ row-to-column element order as specified by lower and upper bound coordinates. - ```mlir + ``` %a = fir.undefined !fir.array<10x10xf32> %c = arith.constant 3.0 : f32 %1 = fir.insert_on_range %a, %c from (0, 0) to (7, 2) : (!fir.array<10x10xf32>, f32) -> !fir.array<10x10xf32> @@ -1995,7 +1995,7 @@ used with the `fir.coordinate_of` instructions to compute (abstract) addresses of LEN parameters. - ```mlir + ``` %e = fir.len_param_index len1, !fir.type %p = ... : !fir.box> %q = fir.coordinate_of %p, %e : (!fir.box>, !fir.len) -> !fir.ref @@ -2062,7 +2062,7 @@ Generalized high-level looping construct. This operation is similar to MLIR's `scf.for`. - ```mlir + ``` %l = arith.constant 0 : index %u = arith.constant 9 : index %s = arith.constant 1 : index @@ -2152,7 +2152,7 @@ Used to conditionally execute operations. This operation is the FIR dialect's version of `loop.if`. - ```mlir + ``` %56 = ... : i1 %78 = ... : !fir.ref fir.if %56 { @@ -2216,7 +2216,7 @@ %ok=phi(%okIn,%okNew), and %sh=phi(%shIn,%shNew) from the last executed iteration. - ```mlir + ``` %v:3 = fir.iterate_while (%i = %lo to %up step %c1) and (%ok = %okIn) iter_args(%sh = %shIn) -> (index, i1, i16) { %shNew = fir.call @bar(%sh) : (i16) -> i16 %okNew = fir.call @foo(%sh) : (i16) -> i1 @@ -2302,7 +2302,7 @@ Provides a custom parser and pretty printer to allow a more readable syntax in the FIR dialect, e.g. `fir.call @sub(%12)` or `fir.call %20(%22,%23)`. - ```mlir + ``` %a = fir.call %funcref(%arg0) : (!fir.ref) -> f32 %b = fir.call @function(%arg1, %arg2) : (!fir.ref, !fir.ref) -> f32 ``` @@ -2367,7 +2367,7 @@ used to select a dispatch operand other than the first one. The absence of `pass_arg_pos` attribute means nopass. - ```mlir + ``` // fir.dispatch with no attribute. %r = fir.dispatch "methodA"(%o) : (!fir.class) -> i32 @@ -2414,7 +2414,7 @@ to Fortran's CHARACTER type, including a LEN. We support CHARACTER values of different KINDs (different constant sizes). - ```mlir + ``` %1 = fir.string_lit "Hello, World!"(13) : !fir.char<1> // ASCII %2 = fir.string_lit [158, 2345](2) : !fir.char<2> // Wide chars ``` @@ -2556,7 +2556,7 @@ used in other operations. References to Fortran symbols are distinguished via this operation from other arbitrary constant values. - ```mlir + ``` %p = fir.address_of(@symbol) : !fir.ref ``` }]; @@ -2577,7 +2577,7 @@ type, this instruction is a NOP and may be folded away. This also supports integer to pointer conversion and pointer to integer conversion. - ```mlir + ``` %v = ... : i64 %w = fir.convert %v : (i64) -> i32 ``` @@ -2620,7 +2620,7 @@ specified type. The meta-type of a type descriptor for the type `T` is `!fir.tdesc`. - ```mlir + ``` !T = !fir.type %t = fir.gentypedesc !T // returns value of !fir.tdesc ``` @@ -2646,7 +2646,7 @@ example below, this would prevent possibly replacing the multiply and add operations with a single FMA operation. - ```mlir + ``` %98 = arith.mulf %96, %97 : f32 %99 = fir.no_reassoc %98 : f32 %a0 = arith.addf %99, %95 : f32 @@ -2671,7 +2671,7 @@ `@_QV_Mquark_Vvarble` with some initial values. The initializer should conform to the variable's type. - ```mlir + ``` fir.global @_QV_Mquark_Vvarble : tuple { %1 = arith.constant 1 : i32 %2 = arith.constant 2.0 : f32 @@ -2770,7 +2770,7 @@ parameter (compile-time) constants associated with the instance's type. These values can be bound to the global instance used `fir.global_len`. - ```mlir + ``` global @g : !fir.type { fir.global_len len1, 10 : i32 %1 = fir.undefined !fir.type @@ -2803,7 +2803,7 @@ The ordering of associations in the map is determined by the front end. - ```mlir + ``` fir.dispatch_table @_QDTMquuzTfoo { fir.dt_entry method1, @_QFNMquuzTfooPmethod1AfooR fir.dt_entry method2, @_QFNMquuzTfooPmethod2AfooII @@ -2848,7 +2848,7 @@ and uses the method identifier to select the type-bound procedure to be called. - ```mlir + ``` fir.dt_entry method_name, @uniquedProcedure ``` }]; @@ -2872,7 +2872,7 @@ a fir.absent operation. It is undefined to use a value that was created by a fir.absent op in any other operation than fir.call and fir.is_present. - ```mlir + ``` %1 = fir.absent fir.box> fir.call @_QPfoo(%1) : (fir.box>) -> () ``` @@ -2889,7 +2889,7 @@ let description = [{ Determine if an optional function argument is PRESENT (i.e. that it was not created by a fir.absent op on the caller side). - ```mlir + ``` func @_QPfoo(%arg0: !fir.box>) { %0 = fir.is_present %arg0 : (!fir.box>) -> i1 ... diff --git a/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md b/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md --- a/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md +++ b/llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md @@ -1,87 +1,87 @@ # Allow Location Descriptions on the DWARF Expression Stack -- [1. Extension](#extension) -- [2. Heterogeneous Computing Devices](#heterogeneous-computing-devices) -- [3. DWARF 5](#dwarf-5) - - [3.1 How DWARF Maps Source Language To Hardware](#how-dwarf-maps-source-language-to-hardware) - - [3.2 Examples](#examples) - - [3.2.1 Dynamic Array Size](#dynamic-array-size) - - [3.2.2 Variable Location in Register](#variable-location-in-register) - - [3.2.3 Variable Location in Memory](#variable-location-in-memory) - - [3.2.4 Variable Spread Across Different Locations](#variable-spread-across-different-locations) - - [3.2.5 Offsetting a Composite Location](#offsetting-a-composite-location) - - [3.2.6 Pointer to Member](#pointer-to-member) - - [3.2.7 Virtual Base Class](#virtual-base-class) - - [3.3 Limitations](#limitations) -- [4. Extension Solution](#extension-solution) - - [4.1 Location Description](#location-description) - - [4.2 Stack Location Description Operations](#stack-location-description-operations) - - [4.3 Examples](#examples-1) - - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#source-language-variable-spilled-to-part-of-a-vector-register) - - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#source-language-variable-spread-across-multiple-vector-registers) - - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#source-language-variable-spread-across-multiple-kinds-of-locations) - - [4.3.4 Address Spaces](#address-spaces) - - [4.3.5 Bit Offsets](#bit-offsets) - - [4.4 Call Frame Information (CFI)](#call-frame-information-cfi) - - [4.5 Objects Not In Byte Aligned Global Memory](#objects-not-in-byte-aligned-global-memory) - - [4.6 Higher Order Operations](#higher-order-operations) - - [4.7 Objects In Multiple Places](#objects-in-multiple-places) -- [5. Conclusion](#conclusion) +- [1. Extension](#1-extension) +- [2. Heterogeneous Computing Devices](#2-heterogeneous-computing-devices) +- [3. DWARF 5](#3-dwarf-5) + - [3.1 How DWARF Maps Source Language To Hardware](#31-how-dwarf-maps-source-language-to-hardware) + - [3.2 Examples](#32-examples) + - [3.2.1 Dynamic Array Size](#321-dynamic-array-size) + - [3.2.2 Variable Location in Register](#322-variable-location-in-register) + - [3.2.3 Variable Location in Memory](#323-variable-location-in-memory) + - [3.2.4 Variable Spread Across Different Locations](#324-variable-spread-across-different-locations) + - [3.2.5 Offsetting a Composite Location](#325-offsetting-a-composite-location) + - [3.2.6 Pointer to Member](#326-pointer-to-member) + - [3.2.7 Virtual Base Class](#327-virtual-base-class) + - [3.3 Limitations](#33-limitations) +- [4. Extension Solution](#4-extension-solution) + - [4.1 Location Description](#41-location-description) + - [4.2 Stack Location Description Operations](#42-stack-location-description-operations) + - [4.3 Examples](#43-examples) + - [4.3.1 Source Language Variable Spilled to Part of a Vector Register](#431-source-language-variable-spilled-to-part-of-a-vector-register) + - [4.3.2 Source Language Variable Spread Across Multiple Vector Registers](#432-source-language-variable-spread-across-multiple-vector-registers) + - [4.3.3 Source Language Variable Spread Across Multiple Kinds of Locations](#433-source-language-variable-spread-across-multiple-kinds-of-locations) + - [4.3.4 Address Spaces](#434-address-spaces) + - [4.3.5 Bit Offsets](#435-bit-offsets) + - [4.4 Call Frame Information (CFI)](#44-call-frame-information-cfi) + - [4.5 Objects Not In Byte Aligned Global Memory](#45-objects-not-in-byte-aligned-global-memory) + - [4.6 Higher Order Operations](#46-higher-order-operations) + - [4.7 Objects In Multiple Places](#47-objects-in-multiple-places) +- [5. Conclusion](#5-conclusion) - [A. Changes to DWARF Debugging Information Format Version 5](#a-changes-to-dwarf-debugging-information-format-version-5) - - [A.2 General Description](#a-2-general-description) - - [A.2.5 DWARF Expressions](#a-2-5-dwarf-expressions) - - [A.2.5.1 DWARF Expression Evaluation Context](#a-2-5-1-dwarf-expression-evaluation-context) - - [A.2.5.2 DWARF Expression Value](#a-2-5-2-dwarf-expression-value) - - [A.2.5.3 DWARF Location Description](#a-2-5-3-dwarf-location-description) - - [A.2.5.4 DWARF Operation Expressions](#a-2-5-4-dwarf-operation-expressions) - - [A.2.5.4.1 Stack Operations](#a-2-5-4-1-stack-operations) - - [A.2.5.4.2 Control Flow Operations](#a-2-5-4-2-control-flow-operations) - - [A.2.5.4.3 Value Operations](#a-2-5-4-3-value-operations) - - [A.2.5.4.3.1 Literal Operations](#a-2-5-4-3-1-literal-operations) - - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a-2-5-4-3-2-arithmetic-and-logical-operations) - - [A.2.5.4.3.3 Type Conversion Operations](#a-2-5-4-3-3-type-conversion-operations) - - [A.2.5.4.3.4 Special Value Operations](#a-2-5-4-3-4-special-value-operations) - - [A.2.5.4.4 Location Description Operations](#a-2-5-4-4-location-description-operations) - - [A.2.5.4.4.1 General Location Description Operations](#a-2-5-4-4-1-general-location-description-operations) - - [A.2.5.4.4.2 Undefined Location Description Operations](#a-2-5-4-4-2-undefined-location-description-operations) - - [A.2.5.4.4.3 Memory Location Description Operations](#a-2-5-4-4-3-memory-location-description-operations) - - [A.2.5.4.4.4 Register Location Description Operations](#a-2-5-4-4-4-register-location-description-operations) - - [A.2.5.4.4.5 Implicit Location Description Operations](#a-2-5-4-4-5-implicit-location-description-operations) - - [A.2.5.4.4.6 Composite Location Description Operations](#a-2-5-4-4-6-composite-location-description-operations) - - [A.2.5.5 DWARF Location List Expressions](#a-2-5-5-dwarf-location-list-expressions) - - [A.3 Program Scope Entries](#a-3-program-scope-entries) - - [A.3.3 Subroutine and Entry Point Entries](#a-3-3-subroutine-and-entry-point-entries) - - [A.3.3.5 Low-Level Information](#a-3-3-5-low-level-information) - - [A.3.4 Call Site Entries and Parameters](#a-3-4-call-site-entries-and-parameters) - - [A.3.4.2 Call Site Parameters](#a-3-4-2-call-site-parameters) - - [A.3.5 Lexical Block Entries](#a-3-5-lexical-block-entries) - - [A.4 Data Object and Object List Entries](#a-4-data-object-and-object-list-entries) - - [A.4.1 Data Object Entries](#a-4-1-data-object-entries) - - [A.5 Type Entries](#a-5-type-entries) - - [A.5.7 Structure, Union, Class and Interface Type Entries](#a-5-7-structure-union-class-and-interface-type-entries) - - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a-5-7-3-derived-or-extended-structures-classes-and-interfaces) - - [A.5.7.8 Member Function Entries](#a-5-7-8-member-function-entries) - - [A.5.14 Pointer to Member Type Entries](#a-5-14-pointer-to-member-type-entries) - - [A.5.16 Dynamic Type Entries](#a-5-16-dynamic-type-entries) - - [A.6 Other Debugging Information](#a-6-other-debugging-information) - - [A.6.2 Line Number Information](#a-6-2-line-number-information) - - [A.6.4 Call Frame Information](#a-6-4-call-frame-information) - - [A.6.4.1 Structure of Call Frame Information](#a-6-4-1-structure-of-call-frame-information) - - [A.6.4.2 Call Frame Instructions](#a-6-4-2-call-frame-instructions) - - [A.6.4.2.1 Row Creation Instructions](#a-6-4-2-1-row-creation-instructions) - - [A.6.4.2.2 CFA Definition Instructions](#a-6-4-2-2-cfa-definition-instructions) - - [A.6.4.2.3 Register Rule Instructions](#a-6-4-2-3-register-rule-instructions) - - [A.6.4.2.4 Row State Instructions](#a-6-4-2-4-row-state-instructions) - - [A.6.4.2.5 Padding Instruction](#a-6-4-2-5-padding-instruction) - - [A.6.4.3 Call Frame Instruction Usage](#a-6-4-3-call-frame-instruction-usage) - - [A.6.4.4 Call Frame Calling Address](#a-6-4-4-call-frame-calling-address) - - [A.7 Data Representation](#a-7-data-representation) - - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a-7-4-32-bit-and-64-bit-dwarf-formats) - - [A.7.5 Format of Debugging Information](#a-7-5-format-of-debugging-information) - - [A.7.5.5 Classes and Forms](#a-7-5-5-classes-and-forms) - - [A.7.7 DWARF Expressions](#a-7-7-dwarf-expressions) - - [A.7.7.1 Operation Expressions](#a-7-7-1-operation-expressions) - - [A.7.7.3 Location List Expressions](#a-7-7-3-location-list-expressions) + - [A.2 General Description](#a2-general-description) + - [A.2.5 DWARF Expressions](#a25-dwarf-expressions) + - [A.2.5.1 DWARF Expression Evaluation Context](#a251-dwarf-expression-evaluation-context) + - [A.2.5.2 DWARF Expression Value](#a252-dwarf-expression-value) + - [A.2.5.3 DWARF Location Description](#a253-dwarf-location-description) + - [A.2.5.4 DWARF Operation Expressions](#a254-dwarf-operation-expressions) + - [A.2.5.4.1 Stack Operations](#a2541-stack-operations) + - [A.2.5.4.2 Control Flow Operations](#a2542-control-flow-operations) + - [A.2.5.4.3 Value Operations](#a2543-value-operations) + - [A.2.5.4.3.1 Literal Operations](#a25431-literal-operations) + - [A.2.5.4.3.2 Arithmetic and Logical Operations](#a25432-arithmetic-and-logical-operations) + - [A.2.5.4.3.3 Type Conversion Operations](#a25433-type-conversion-operations) + - [A.2.5.4.3.4 Special Value Operations](#a25434-special-value-operations) + - [A.2.5.4.4 Location Description Operations](#a2544-location-description-operations) + - [A.2.5.4.4.1 General Location Description Operations](#a25441-general-location-description-operations) + - [A.2.5.4.4.2 Undefined Location Description Operations](#a25442-undefined-location-description-operations) + - [A.2.5.4.4.3 Memory Location Description Operations](#a25443-memory-location-description-operations) + - [A.2.5.4.4.4 Register Location Description Operations](#a25444-register-location-description-operations) + - [A.2.5.4.4.5 Implicit Location Description Operations](#a25445-implicit-location-description-operations) + - [A.2.5.4.4.6 Composite Location Description Operations](#a25446-composite-location-description-operations) + - [A.2.5.5 DWARF Location List Expressions](#a255-dwarf-location-list-expressions) + - [A.3 Program Scope Entries](#a3-program-scope-entries) + - [A.3.3 Subroutine and Entry Point Entries](#a33-subroutine-and-entry-point-entries) + - [A.3.3.5 Low-Level Information](#a335-low-level-information) + - [A.3.4 Call Site Entries and Parameters](#a34-call-site-entries-and-parameters) + - [A.3.4.2 Call Site Parameters](#a342-call-site-parameters) + - [A.3.5 Lexical Block Entries](#a35-lexical-block-entries) + - [A.4 Data Object and Object List Entries](#a4-data-object-and-object-list-entries) + - [A.4.1 Data Object Entries](#a41-data-object-entries) + - [A.5 Type Entries](#a5-type-entries) + - [A.5.7 Structure, Union, Class and Interface Type Entries](#a57-structure-union-class-and-interface-type-entries) + - [A.5.7.3 Derived or Extended Structures, Classes and Interfaces](#a573-derived-or-extended-structures-classes-and-interfaces) + - [A.5.7.8 Member Function Entries](#a578-member-function-entries) + - [A.5.14 Pointer to Member Type Entries](#a514-pointer-to-member-type-entries) + - [A.5.18 Dynamic Properties of Types](#a518-dynamic-properties-of-types) + - [A.6 Other Debugging Information](#a6-other-debugging-information) + - [A.6.2 Line Number Information](#a62-line-number-information) + - [A.6.4 Call Frame Information](#a64-call-frame-information) + - [A.6.4.1 Structure of Call Frame Information](#a641-structure-of-call-frame-information) + - [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions) + - [A.6.4.2.1 Row Creation Instructions](#a6421-row-creation-instructions) + - [A.6.4.2.2 CFA Definition Instructions](#a6422-cfa-definition-instructions) + - [A.6.4.2.3 Register Rule Instructions](#a6423-register-rule-instructions) + - [A.6.4.2.4 Row State Instructions](#a6424-row-state-instructions) + - [A.6.4.2.5 Padding Instruction](#a6425-padding-instruction) + - [A.6.4.3 Call Frame Instruction Usage](#a643-call-frame-instruction-usage) + - [A.6.4.4 Call Frame Calling Address](#a644-call-frame-calling-address) + - [A.7 Data Representation](#a7-data-representation) + - [A.7.4 32-Bit and 64-Bit DWARF Formats](#a74-32-bit-and-64-bit-dwarf-formats) + - [A.7.5 Format of Debugging Information](#a75-format-of-debugging-information) + - [A.7.5.5 Classes and Forms](#a755-classes-and-forms) + - [A.7.7 DWARF Expressions](#a77-dwarf-expressions) + - [A.7.7.1 Operation Expressions](#a771-operation-expressions) + - [A.7.7.3 Location List Expressions](#a773-location-list-expressions) - [B. Further Information](#b-further-information) # 1. Extension @@ -112,15 +112,15 @@ consistent semantics regardless of context. First, section [2. Heterogeneous Computing -Devices](#heterogeneous-computing-devices) describes heterogeneous devices and +Devices](#2-heterogeneous-computing-devices) describes heterogeneous devices and the features they have that are not addressed by DWARF 5. Then section [3. DWARF -5](#dwarf-5) presents a brief simplified overview of the DWARF 5 expression +5](#3-dwarf-5) presents a brief simplified overview of the DWARF 5 expression evaluation model that highlights the difficulties for supporting the heterogeneous features. Next, section [4. Extension -Solution](#extension-solution) provides an overview of the proposal, using +Solution](#4-extension-solution) provides an overview of the proposal, using simplified examples to illustrate how it can address the issues of heterogeneous devices and also benefit non-heterogeneous devices. Then overall conclusions are -covered in section [5. Conclusion](#conclusion). Appendix [A. Changes to DWARF +covered in section [5. Conclusion](#5-conclusion). Appendix [A. Changes to DWARF Debugging Information Format Version 5](#a-changes-to-dwarf-debugging-information-format-version-5) gives changes relative to the DWARF Version 5 standard. Finally, appendix [B. Further @@ -417,7 +417,7 @@ This example attempts to extend the previous example to offset the composite location description it created. The [3.2.3 Variable Location in -Memory](#variable-location-in-memory) example conveniently used the DW_OP_plus +Memory](#323-variable-location-in-memory) example conveniently used the DW_OP_plus operation to offset a memory address. DW_OP_regx SGPR3 @@ -625,7 +625,7 @@ With location descriptions on the stack, the definition of `DW_OP_use_location` can be modified by replacing every instance of "address" with "location -description", as is described in [A.5 Type Entries](#a-5-type-entries). +description", as is described in [A.5 Type Entries](#a5-type-entries). To implement the fully generalized version of this attribute, GCC would only need to change the expression from `DW_OP_plus` to `DW_OP_swap, @@ -729,9 +729,10 @@ location of `B` by the dynamic value of `vbase_offset` (in this case `8`) to arrive at the location of the inherited subobject. -This definition shares the same problem as example [3.2.6](#pointer-to-member) -in that it relies on the address of the derived object and inherited subobject, -when there is no guarantee either or both have any address at all. +This definition shares the same problem as example +[3.2.6](#326-pointer-to-member) in that it relies on the address of the derived +object and inherited subobject, when there is no guarantee either or both have +any address at all. To demonstrate the problem, consider a program which GCC chooses to optimize in such a way that the derived object is not in memory at all: @@ -812,7 +813,7 @@ With location descriptions on the stack, the definition of `DW_OP_data_member_location` can be modified by replacing every instance of "address" with "location description", as is described in [A.5 Type -Entries](#a-5-type-entries). +Entries](#a5-type-entries). To implement the fully generalized version of this attribute, GCC would only need to change the last operation in the expression from `DW_OP_plus` to @@ -1345,11 +1346,11 @@ DW_OP_push_object_address operation, may want to act on the result of another expression that returned a location description involving multiple places. -Therefore, the extension needs to define how expression operations that use those -results will behave. The extension does this by generalizing the expression stack -to allow an entry to be one or more single location descriptions. In doing this, -it unifies the definitions of DWARF operation expressions and loclist -expressions in a natural way. +Therefore, the extension needs to define how expression operations that use +those results will behave. The extension does this by generalizing the +expression stack to allow an entry to be one or more single location +descriptions. In doing this, it unifies the definitions of DWARF operation +expressions and loclist expressions in a natural way. All operations that act on location descriptions are extended to act on multiple single location descriptions. For example, the DW_OP_offset operation adds the @@ -1399,16 +1400,16 @@ itself, and so on. If the evaluation of a DWARF expression does not encounter an error, then it can -either result in a value (see [2.5.2 DWARF Expression -Value](#dwarf-expression-value)) or a location description (see [2.5.3 DWARF -Location Description](#dwarf-location-description)). When a DWARF expression -is evaluated, it may be specified whether a value or location description is -required as the result kind. +either result in a value (see [A.2.5.2 DWARF Expression +Value](#a252-dwarf-expression-value)) or a location description (see [A.2.5.3 +DWARF Location Description](#a253-dwarf-location-description)). When a DWARF +expression is evaluated, it may be specified whether a value or location +description is required as the result kind. If a result kind is specified, and the result of the evaluation does not match -the specified result kind, then the implicit conversions described in [2.5.4.4.3 -Memory Location Description -Operations](#memory-location-description-operations) are performed if +the specified result kind, then the implicit conversions described in +[A.2.5.4.4.3 Memory Location Description +Operations](#a25443-memory-location-description-operations) are performed if valid. Otherwise, the DWARF expression is ill-formed. If the evaluation of a DWARF expression encounters an evaluation error, then the @@ -1432,10 +1433,10 @@ The following sections detail the rules for when a DWARF expression is ill-formed or results in an evaluation error. -A DWARF expression can either be encoded as an operation expression (see [2.5.4 -DWARF Operation Expressions](#dwarf-operation-expressions)), or as a -location list expression (see [2.5.5 DWARF Location List -Expressions](#dwarf-location-list-expressions)). +A DWARF expression can either be encoded as an operation expression (see +[A.2.5.4 DWARF Operation Expressions](#a254-dwarf-operation-expressions)), or as +a location list expression (see [A.2.5.5 DWARF Location List +Expressions](#a255-dwarf-location-list-expressions)). #### A.2.5.1 DWARF Expression Evaluation Context @@ -1467,7 +1468,8 @@ thread. It is identified by its address on the call stack. The address is referred to as the Canonical Frame Address (CFA). The call frame information is used to determine the CFA for the call frames of the current thread's - call stack (see [6.4 Call Frame Information](#call-frame-information)). + call stack (see [A.6.4 Call Frame + Information](#a64-call-frame-information)). It is required for operations that specify target architecture registers to support virtual unwinding of the call stack. @@ -1488,13 +1490,13 @@ The program location of the top call frame is the target architecture program counter for the current thread. The call frame information is used to obtain the value of the return address register to determine the program - location of the other call frames (see [6.4 Call Frame - Information](#call-frame-information)). + location of the other call frames (see [A.6.4 Call Frame + Information](#a64-call-frame-information)). It is required for the evaluation of location list expressions to select amongst multiple program location ranges. It is required for operations that specify target architecture registers to support virtual unwinding of the - call stack (see [6.4 Call Frame Information](#call-frame-information)). + call stack (see [A.6.4 Call Frame Information](#a64-call-frame-information)). If specified: @@ -1551,8 +1553,8 @@ associated entry in the `.debug_aranges` section. - If the current program location is specified, then the current target architecture must be the same as the target architecture of any line - number information entry (see [6.2 Line Number - Information](#line-number-information)) corresponding to the current + number information entry (see [A.6.2 Line Number + Information](#a62-line-number-information)) corresponding to the current program location. - If the current program location is specified, then the current target architecture default address space address size must be the same as the @@ -1573,8 +1575,8 @@ descriptor as the current object when it evaluates its associated expression. - The result is undefined if the location description is invalid (see [2.5.3 - DWARF Location Description](#dwarf-location-description)). + The result is undefined if the location description is invalid (see [A.2.5.3 + DWARF Location Description](#a253-dwarf-location-description)). 8. An initial stack @@ -1586,8 +1588,8 @@ expression value with initial stack entries. In all other cases the initial stack is empty. - The result is undefined if any location descriptions are invalid (see [2.5.3 - DWARF Location Description](#dwarf-location-description)). + The result is undefined if any location descriptions are invalid (see + [A.2.5.3 DWARF Location Description](#a253-dwarf-location-description)). If the evaluation requires a context element that is not specified, then the result of the evaluation is an error. @@ -1598,8 +1600,8 @@ such context. If the expression evaluates with an error then it may indicate the variable has been optimized and so requires more context. -The DWARF expression for call frame information (see [6.4 Call Frame -Information](#call-frame-information)) operations are restricted to those +The DWARF expression for call frame information (see [A.6.4 Call Frame +Information](#a64-call-frame-information)) operations are restricted to those that do not require the compilation unit context to be specified. The DWARF is ill-formed if all the `address_size` fields in the headers of all @@ -1697,9 +1699,9 @@ - They can be the result of evaluating a debugger information entry attribute that specifies an operation expression of arbitrary complexity. In this usage they can describe the location of an object as long as its lifetime is either - static or the same as the lexical block (see [3.5 Lexical Block - Entries](#lexical-block-entries)) that owns it, and it does not move during - its lifetime. + static or the same as the lexical block (see [A.3.5 Lexical Block + Entries](#a35-lexical-block-entries)) that owns it, and it does not move + during its lifetime. - They can be the result of evaluating a debugger information entry attribute that specifies a location list expression. In this usage they can describe the @@ -1794,8 +1796,8 @@ entry can hold either a value or a location description. Operations can act on entries on the stack, including adding entries and removing entries. If the kind of a stack entry does not match the kind required by the operation and is not -implicitly convertible to the required kind (see [2.5.4.4.3 Memory Location -Description Operations](#memory-location-description-operations)), then +implicitly convertible to the required kind (see [A.2.5.4.4.3 Memory Location +Description Operations](#a25443-memory-location-description-operations)), then the DWARF operation expression is ill-formed. Evaluation of an operation expression starts with an empty stack on which the @@ -1817,10 +1819,10 @@ an empty operation expression for this purpose. - If the top stack entry is a location description, or can be converted to one - (see [2.5.4.4.3 Memory Location Description - Operations](#memory-location-description-operations)), then the result - is that, possibly converted, location description. Any other entries on the - stack are discarded. + (see [A.2.5.4.4.3 Memory Location Description + Operations](#a25443-memory-location-description-operations)), then the + result is that, possibly converted, location description. Any other entries + on the stack are discarded. - Otherwise the DWARF expression is ill-formed. > NOTE: Could define this case as returning an implicit location description @@ -1828,10 +1830,10 @@ - If the current result kind specifies a value, then: - If the top stack entry is a value, or can be converted to one (see - [2.5.4.4.3 Memory Location Description - Operations](#memory-location-description-operations)), then the result is - that, possibly converted, value. Any other entries on the stack are - discarded. + [A.2.5.4.4.3 Memory Location Description + Operations](#a25443-memory-location-description-operations)), then the + result is that, possibly converted, value. Any other entries on the stack + are discarded. - Otherwise the DWARF expression is ill-formed. - If the current result kind is not specified, then: - If the stack is empty, the result is a location description with one @@ -1851,12 +1853,12 @@ specifies the byte count. It can be used: - as the value of a debugging information entry attribute that is encoded using - class `exprloc` (see [7.5.5 Classes and Forms](#classes-and-forms)), + class `exprloc` (see [A.7.5.5 Classes and Forms](#a755-classes-and-forms)), - as the operand to certain operation expression operations, -- as the operand to certain call frame information operations (see [6.4 Call - Frame Information](#call-frame-information)), -- and in location list entries (see [2.5.5 DWARF Location List - Expressions](#dwarf-location-list-expressions)). +- as the operand to certain call frame information operations (see [A.6.4 Call + Frame Information](#a64-call-frame-information)), +- and in location list entries (see [A.2.5.5 DWARF Location List + Expressions](#a255-dwarf-location-list-expressions)). ##### A.2.5.4.1 Stack Operations @@ -1867,8 +1869,8 @@ They allow the stack entries to be either a value or location description. If any stack entry accessed by a stack operation is an incomplete composite -location description (see [2.5.4.4.6 Composite Location Description -Operations](#composite-location-description-operations)), then the DWARF +location description (see [A.2.5.4.4.6 Composite Location Description +Operations](#a25446-composite-location-description-operations)), then the DWARF expression is ill-formed. > NOTE: These operations now support stack entries that are values and location @@ -2346,8 +2348,8 @@ undefined location storage or the offset of any bit exceeds the size of the location storage LS specified by any single location description SL of L. - See [2.5.4.4.5 Implicit Location Description - Operations](#implicit-location-description-operations) for special + See [A.2.5.4.4.5 Implicit Location Description + Operations](#a25445-implicit-location-description-operations) for special rules concerning implicit location descriptions created by the `DW_OP_implicit_pointer` operation. @@ -2435,12 +2437,12 @@ program location is the call site in the calling frame, the object is unspecified, and the initial stack is empty. The calling frame information is obtained by virtually unwinding the current call frame using the call - frame information (see [6.4 Call Frame - Information](#call-frame-information)). + frame information (see [A.6.4 Call Frame + Information](#a64-call-frame-information)). - If the result of E is a location description L (see [2.5.4.4.4 Register + If the result of E is a location description L (see [A.2.5.4.4.4 Register Location Description - Operations](#register-location-description-operations)), and the last + Operations](#a25444-register-location-description-operations)), and the last operation executed by E is a `DW_OP_reg*` for register R with a target architecture specific base type of T, then the contents of the register are retrieved as if a `DW_OP_deref_type DR` operation was performed where DR is @@ -2606,8 +2608,8 @@ If a stack entry is required to be a location description, but it is an implicit pointer value IPV with the target architecture default address space, then it is implicitly converted to a location description with one single location -description specified by IPV. See [2.5.4.4.5 Implicit Location Description -Operations](#implicit-location-description-operations). +description specified by IPV. See [A.2.5.4.4.5 Implicit Location Description +Operations](#a25445-implicit-location-description-operations). If a stack entry is required to be a value, but it is a location description L with one memory location description SL in the target architecture default @@ -2683,8 +2685,8 @@ `DW_OP_call_frame_cfa` pushes the location description L of the Canonical Frame Address (CFA) of the current subprogram, obtained from the call frame - information on the stack. See [6.4 Call Frame - Information](#call-frame-information). + information on the stack. See [A.6.4 Call Frame + Information](#a64-call-frame-information). Although the value of the `DW_AT_frame_base` attribute of the debugger information entry corresponding to the current subprogram can be computed @@ -2703,7 +2705,7 @@ The location description L for the frame base of the current subprogram is obtained from the `DW_AT_frame_base` attribute of the debugger information entry corresponding to the current subprogram as described in - [3.3.5 Low-Level Information](#low-level-information). + [A.3.3.5 Low-Level Information](#a335-low-level-information). The location description L is updated by bit offset B scaled by 8 (the byte size) and pushed on the stack. @@ -2775,7 +2777,7 @@ a bit offset of 0 for the current thread. If the current call frame is not the top call frame, call frame information - (see [6.4 Call Frame Information](#call-frame-information)) is used to + (see [A.6.4 Call Frame Information](#a64-call-frame-information)) is used to determine the location description that holds the register for the current call frame and current program location of the current thread. The resulting location description L is pushed. @@ -3194,10 +3196,10 @@ A location list expression can only be used as the value of a debugger information entry attribute that is encoded using class `loclist` or -`loclistsptr` (see [7.5.5 Classes and Forms](#classes-and-forms)). The value of -the attribute provides an index into a separate object file section called -`.debug_loclists` or `.debug_loclists.dwo` (for split DWARF object files) that -contains the location list entries. +`loclistsptr` (see [A.7.5.5 Classes and Forms](#a755-classes-and-forms)). The +value of the attribute provides an index into a separate object file section +called `.debug_loclists` or `.debug_loclists.dwo` (for split DWARF object files) +that contains the location list entries. A `DW_OP_call*` and `DW_OP_implicit_pointer` operation can be used to specify a debugger information entry attribute that has a location list expression. @@ -3286,8 +3288,8 @@ compilation unit that contains E, an empty initial stack, and other context elements corresponding to the source language thread of execution upon which the user is focused, if any. The result of the evaluation is the location - description L of the canonical frame address (see [6.4 Call Frame - Information](#call-frame-information)) of the relevant call frame of the + description L of the canonical frame address (see [A.6.4 Call Frame + Information](#a64-call-frame-information)) of the relevant call frame of the subprogram instance that immediately lexically encloses the current call frame's subprogram or entry point. @@ -3344,11 +3346,11 @@ `DW_TAG_call_site_parameter` debugger information entry in the current call frame. - The consumer may have to virtually unwind to the call site (see [6.4 Call - Frame Information](#call-frame-information)) in order to evaluate these - attributes. This will ensure the source language thread of execution upon which - the user is focused corresponds to the call site needed to evaluate the - expression. + The consumer may have to virtually unwind to the call site (see [A.6.4 + Call Frame Information](#a64-call-frame-information)) in order to evaluate + these attributes. This will ensure the source language thread of execution + upon which the user is focused corresponds to the call site needed to + evaluate the expression. If it is not possible to avoid the expressions of these attributes from accessing registers or memory locations that might be clobbered by the @@ -3358,8 +3360,8 @@ The reason for the restriction is that the parameter may need to be accessed during the execution of the callee. The consumer may virtually unwind from the called subprogram back to the caller and then evaluate the attribute - expressions. The call frame information (see [6.4 Call Frame - Information](#call-frame-information)) will not be able to restore registers + expressions. The call frame information (see [A.6.4 Call Frame + Information](#a64-call-frame-information)) will not be able to restore registers that have been clobbered, and clobbered memory will no longer have the value at the time of the call. @@ -3394,8 +3396,8 @@ the user is focused, if any. The result of the evaluation is the location description of the base of the data object. - See [2.5.4.2 Control Flow Operations](#control-flow-operations) for special - evaluation rules used by the `DW_OP_call*` operations. + See [A.2.5.4.2 Control Flow Operations](#a2542-control-flow-operations) for + special evaluation rules used by the `DW_OP_call*` operations. > NOTE: Delete the description of how the `DW_OP_call*` operations evaluate > a `DW_AT_location` attribute as that is now described in the operations. @@ -3573,8 +3575,8 @@ A register that has this rule has no recoverable value in the previous frame. The previous value of this register is the undefined location - description (see [2.5.4.4.2 Undefined Location Description - Operations](#undefined-location-description-operations)). + description (see [A.2.5.4.4.2 Undefined Location Description + Operations](#a25442-undefined-location-description-operations)). By convention, the register is not preserved by a callee. @@ -3599,17 +3601,17 @@ N is a signed byte offset. The previous value of this register is saved at the location description L. Where L is the location description of the - current CFA (see [2.5.4 DWARF Operation - Expressions](#dwarf-operation-expressions)) updated with the bit offset N - scaled by 8 (the byte size). + current CFA (see [A.2.5.4 DWARF Operation + Expressions](#a254-dwarf-operation-expressions)) updated with the bit offset + N scaled by 8 (the byte size). 4. val_offset(N) N is a signed byte offset. The previous value of this register is the memory byte address of the location description L. Where L is the location - description of the current CFA (see [2.5.4 DWARF Operation - Expressions](#dwarf-operation-expressions)) updated with the bit offset N - scaled by 8 (the byte size). + description of the current CFA (see [A.2.5.4 DWARF Operation + Expressions](#a254-dwarf-operation-expressions)) updated with the bit offset + N scaled by 8 (the byte size). The DWARF is ill-formed if the CFA location description is not a memory byte address location description, or if the register size does not match the @@ -3653,26 +3655,26 @@ 6. expression(E) The previous value of this register is located at the location description - produced by evaluating the DWARF operation expression E (see [2.5.4 DWARF - Operation Expressions](#dwarf-operation-expressions)). + produced by evaluating the DWARF operation expression E (see [A.2.5.4 DWARF + Operation Expressions](#a254-dwarf-operation-expressions)). E is evaluated with the current context, except the result kind is a location description, the compilation unit is unspecified, the object is unspecified, and an initial stack comprising the location description of the - current CFA (see [2.5.4 DWARF Operation - Expressions](#dwarf-operation-expressions)). + current CFA (see [A.2.5.4 DWARF Operation + Expressions](#a254-dwarf-operation-expressions)). 7. val_expression(E) The previous value of this register is located at the implicit location description created from the value produced by evaluating the DWARF - operation expression E (see [2.5.4 DWARF Operation - Expressions](#dwarf-operation-expressions)). + operation expression E (see [A.2.5.4 DWARF Operation + Expressions](#a254-dwarf-operation-expressions)). E is evaluated with the current context, except the result kind is a value, the compilation unit is unspecified, the object is unspecified, and an initial stack comprising the location description of the current CFA (see - [2.5.4 DWARF Operation Expressions](#dwarf-operation-expressions)). + [A.2.5.4 DWARF Operation Expressions](#a254-dwarf-operation-expressions)). The DWARF is ill-formed if the resulting value type size does not match the register size. @@ -3699,8 +3701,8 @@ value of length must be an integral multiple of the address size specified in the `address_size` field. -2. `CIE_id` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF - Formats](#32-bit-and-64-bit-dwarf-formats)) +2. `CIE_id` (4 or 8 bytes, see [A.7.4 32-Bit and 64-Bit DWARF + Formats](#a74-32-bit-and-64-bit-dwarf-formats)) A constant that is used to distinguish CIEs from FDEs. @@ -3752,15 +3754,17 @@ 7. `code_alignment_factor` (unsigned LEB128) A constant that is factored out of all advance location instructions (see - [6.4.2.1 Row Creation Instructions](#row-creation-instructions)). The - resulting value is `(operand * code_alignment_factor)`. + [A.6.4.2.1 Row Creation + Instructions](#a6421-row-creation-instructions)). The resulting value is + `(operand * code_alignment_factor)`. 8. `data_alignment_factor` (signed LEB128) - A constant that is factored out of certain offset instructions (see [6.4.2.2 - CFA Definition Instructions](#cfa-definition-instructions) and [6.4.2.3 - Register Rule Instructions](#register-rule-instructions)). The - resulting value is `(operand * data_alignment_factor)`. + A constant that is factored out of certain offset instructions (see + [A.6.4.2.2 CFA Definition Instructions](#a6422-cfa-definition-instructions) + and [A.6.4.2.3 Register Rule + Instructions](#a6423-register-rule-instructions)). The resulting value is + `(operand * data_alignment_factor)`. 9. `return_address_register` (unsigned LEB128) @@ -3796,8 +3800,8 @@ of the length field plus the value of length must be an integral multiple of the address size. -2. `CIE_pointer` (4 or 8 bytes, see [7.4 32-Bit and 64-Bit DWARF - Formats](#32-bit-and-64-bit-dwarf-formats)) +2. `CIE_pointer` (4 or 8 bytes, see [A.7.4 32-Bit and 64-Bit DWARF + Formats](#a74-32-bit-and-64-bit-dwarf-formats)) A constant offset into the `.debug_frame` section that denotes the CIE that is associated with this FDE. @@ -3814,8 +3818,8 @@ 5. `instructions` (array of ubyte) - A sequence of table defining instructions that are described in [6.4.2 Call - Frame Instructions](#call-frame-instructions). + A sequence of table defining instructions that are described in [A.6.4.2 Call + Frame Instructions](#a642-call-frame-instructions). 6. `padding` (array of ubyte) @@ -3825,8 +3829,8 @@ #### A.6.4.2 Call Frame Instructions Some call frame instructions have operands that are encoded as DWARF operation -expressions E (see [2.5.4 DWARF Operation -Expressions](#dwarf-operation-expressions)). The DWARF operations that can be +expressions E (see [A.2.5.4 DWARF Operation +Expressions](#a254-dwarf-operation-expressions)). The DWARF operations that can be used in E have the following restrictions: - `DW_OP_addrx`, `DW_OP_call2`, `DW_OP_call4`, `DW_OP_call_ref`, @@ -3913,8 +3917,9 @@ is a location description, the compilation unit is unspecified, the object is unspecified, and an empty initial stack. - See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding - restrictions on the DWARF expression operations that can be used in E. + See [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions) + regarding restrictions on the DWARF expression operations that can be used + in E. The DWARF is ill-formed if the result of evaluating E is not a memory byte address location description. @@ -3996,8 +4001,9 @@ That is, E computes the location description where the register value can be retrieved. - See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding - restrictions on the DWARF expression operations that can be used in E. + See [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions) + regarding restrictions on the DWARF expression operations that can be used + in E. 10. `DW_CFA_val_expression` @@ -4009,8 +4015,9 @@ That is, E computes the value of register R. - See [6.4.2 Call Frame Instructions](#call-frame-instructions) regarding - restrictions on the DWARF expression operations that can be used in E. + See [A.6.4.2 Call Frame Instructions](#a642-call-frame-instructions) + regarding restrictions on the DWARF expression operations that can be used + in E. If the result of evaluating E is not a value with a base type size that matches the register size, then the DWARF is ill-formed. diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -887,6 +887,8 @@ should request the target to be enabled by default by sending another RFC to the `LLVM Discourse forums`_. +.. _adding an established project to the LLVM monorepo: + Adding an Established Project To the LLVM Monorepo -------------------------------------------------- diff --git a/llvm/docs/GitRepositoryPolicy.md b/llvm/docs/GitRepositoryPolicy.md --- a/llvm/docs/GitRepositoryPolicy.md +++ b/llvm/docs/GitRepositoryPolicy.md @@ -20,7 +20,7 @@ If you want to integrate your project as part of the Monorepo, please take a look at the -[Developer Policy](DeveloperPolicy.html#adding-an-established-project-to-the-llvm-monorepo>). +[Developer Policy](adding an established project to the LLVM monorepo). To request a new repository, please create an issue with the [Infrastructure Working Group](https://github.com/llvm/llvm-iwg/issues). diff --git a/llvm/docs/MarkdownQuickstartTemplate.md b/llvm/docs/MarkdownQuickstartTemplate.md --- a/llvm/docs/MarkdownQuickstartTemplate.md +++ b/llvm/docs/MarkdownQuickstartTemplate.md @@ -151,11 +151,11 @@ If you need to do fancier things than what has been shown in this document, you can mail the list or check the [Common Mark spec]. Sphinx specific -integration documentation can be found in the [recommonmark docs]. +integration documentation can be found in the [MyST docs]. [Common Mark spec]: http://spec.commonmark.org/0.28/ -[recommonmark docs]: http://recommonmark.readthedocs.io/en/latest/index.html +[MyST docs]: https://myst-parser.readthedocs.io/en/latest/ ## Generating the documentation -see [Sphinx Quickstart Template](SphinxQuickstartTemplate.html#generating-the-documentation) +see [Sphinx Quickstart Template](generating the documentation) diff --git a/llvm/docs/PointerAuth.md b/llvm/docs/PointerAuth.md --- a/llvm/docs/PointerAuth.md +++ b/llvm/docs/PointerAuth.md @@ -16,7 +16,7 @@ * a [call operand bundle](#operand-bundle) (to authenticate called pointers) The current implementation leverages the -[Armv8.3-A PAuth/Pointer Authentication Code](#armv8-3-a-pauth-pointer-authentication-code) +[Armv8.3-A PAuth/Pointer Authentication Code](#armv83-a-pauth-pointer-authentication-code) instructions in the [AArch64 backend](#aarch64-support). This support is used to implement the Darwin arm64e ABI, as well as the [PAuth ABI Extension to ELF](https://github.com/ARM-software/abi-aa/blob/main/pauthabielf64/pauthabielf64.rst). @@ -117,7 +117,7 @@ signature is valid. ``key`` should identify a key that is appropriate for ``value``, as defined -by the target-specific [keys](#key)). +by the target-specific [keys](#keys)). If ``value`` is a raw pointer value, it is returned as-is (provided the ``key`` is appropriate for the pointer). @@ -192,7 +192,7 @@ It returns a full signature value (as opposed to a signed pointer value, with an embedded partial signature). -As opposed to [``llvm.ptrauth.sign``](#llvm-ptrauth-sign), it does not interpret +As opposed to [``llvm.ptrauth.sign``](#llvmptrauthsign), it does not interpret ``value`` as a pointer value. Instead, it is an arbitrary data value. @@ -226,7 +226,7 @@ Function pointers used as indirect call targets can be signed when materialized, and authenticated before calls. This can be accomplished with the -[``llvm.ptrauth.auth``](#llvm-ptrauth-auth) intrinsic, feeding its result to +[``llvm.ptrauth.auth``](#llvmptrauthauth) intrinsic, feeding its result to an indirect call. However, that exposes the intermediate, unauthenticated pointer, e.g., if it @@ -235,7 +235,7 @@ To prevent that, the ``ptrauth`` operand bundle may be used: it guarantees that the intermediate call target is kept in a register and never stored to memory. This hardening benefit is similar to that provided by -[``llvm.ptrauth.resign``](#llvm-ptrauth-resign)). +[``llvm.ptrauth.resign``](#llvmptrauthresign)). Concretely: @@ -283,20 +283,20 @@ ``ASGA`` is a special key that cannot be explicitly specified, and is only ever used implicitly, to implement the -[``llvm.ptrauth.sign_generic``](#llvm-ptrauth-sign-generic) intrinsic. +[``llvm.ptrauth.sign_generic``](#llvmptrauthsign_generic) intrinsic. #### Instructions The IR [Intrinsics](#intrinsics) described above map onto these instructions as such: -* [``llvm.ptrauth.sign``](#llvm-ptrauth-sign): ``PAC{I,D}{A,B}{Z,SP,}`` -* [``llvm.ptrauth.auth``](#llvm-ptrauth-auth): ``AUT{I,D}{A,B}{Z,SP,}`` -* [``llvm.ptrauth.strip``](#llvm-ptrauth-strip): ``XPAC{I,D}`` -* [``llvm.ptrauth.blend``](#llvm-ptrauth-blend): The semantics of the blend +* [``llvm.ptrauth.sign``](#llvmptrauthsign): ``PAC{I,D}{A,B}{Z,SP,}`` +* [``llvm.ptrauth.auth``](#llvmptrauthauth): ``AUT{I,D}{A,B}{Z,SP,}`` +* [``llvm.ptrauth.strip``](#llvmptrauthstrip): ``XPAC{I,D}`` +* [``llvm.ptrauth.blend``](#llvmptrauthblend): The semantics of the blend operation are specified by the ABI. In both the ELF PAuth ABI Extension and arm64e, it's a ``MOVK`` into the high 16 bits. Consequently, this limits the width of the integer discriminator used in blends to 16 bits. -* [``llvm.ptrauth.sign_generic``](#llvm-ptrauth-sign-generic): ``PACGA`` -* [``llvm.ptrauth.resign``](#llvm-ptrauth-resign): ``AUT*+PAC*``. These are +* [``llvm.ptrauth.sign_generic``](#llvmptrauthsign_generic): ``PACGA`` +* [``llvm.ptrauth.resign``](#llvmptrauthresign): ``AUT*+PAC*``. These are represented as a single pseudo-instruction in the backend to guarantee that the intermediate raw pointer value is not spilled and attackable. diff --git a/llvm/docs/SpeculativeLoadHardening.md b/llvm/docs/SpeculativeLoadHardening.md --- a/llvm/docs/SpeculativeLoadHardening.md +++ b/llvm/docs/SpeculativeLoadHardening.md @@ -1,6 +1,6 @@ # Speculative Load Hardening -### A Spectre Variant #1 Mitigation Technique +## A Spectre Variant #1 Mitigation Technique Author: Chandler Carruth - [chandlerc@google.com](mailto:chandlerc@google.com) diff --git a/llvm/docs/SphinxQuickstartTemplate.rst b/llvm/docs/SphinxQuickstartTemplate.rst --- a/llvm/docs/SphinxQuickstartTemplate.rst +++ b/llvm/docs/SphinxQuickstartTemplate.rst @@ -164,7 +164,8 @@ .++:.. ... - +.. _generating the documentation: + Generating the documentation ============================ @@ -172,19 +173,19 @@ see what they would look like. In addition to the normal `build tools `_ you need to install `Sphinx`_ and the -`recommonmark `_ extension. +`myst-parser `_ extension. On Debian you can install these with: .. code-block:: console - sudo apt install -y sphinx-doc python-recommonmark-doc + sudo apt install -y sphinx-doc python3-myst-parser -On Ubuntu use pip to get an up-to-date version of recommonmark: +On Ubuntu use pip to get an up-to-date version of myst-parser: .. code-block:: console - sudo pip install sphinx recommonmark + sudo pip install sphinx myst-parser Then run cmake to build the documentation inside the ``llvm-project`` checkout: diff --git a/llvm/docs/conf.py b/llvm/docs/conf.py --- a/llvm/docs/conf.py +++ b/llvm/docs/conf.py @@ -37,7 +37,7 @@ } try: - import recommonmark + import myst_parser except ImportError: # manpages do not use any .md sources if not tags.has('builder-man'): @@ -46,10 +46,11 @@ import sphinx if sphinx.version_info >= (3, 0): # This requires 0.5 or later. - extensions.append('recommonmark') + extensions.append('myst_parser') else: - source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'} + source_parsers = {'.md': 'myst_parser.parsers.sphinx_.MystParser'} source_suffix['.md'] = 'markdown' + myst_heading_anchors = 7 # The encoding of source files. #source_encoding = 'utf-8-sig' diff --git a/llvm/utils/release/build-docs.sh b/llvm/utils/release/build-docs.sh --- a/llvm/utils/release/build-docs.sh +++ b/llvm/utils/release/build-docs.sh @@ -15,7 +15,7 @@ # ninja-build gcc-c++ # * pip install sphinx-markdown-tables # * Ubuntu: -# * apt-get install doxygen sphinx-common python3-recommonmark \ +# * apt-get install doxygen sphinx-common python3-myst-parser \ # ninja-build graphviz texlive-font-utils # * pip install sphinx-markdown-tables #===------------------------------------------------------------------------===#