Attached is an updated patch for both tree.h and the internals manual
documenting the most important BLOCK_ macros and what they represent.

On 1/21/21 2:52 PM, Martin Sebor wrote:
> On 1/18/21 6:25 AM, Richard Biener wrote:
>>> PS Here are my notes on the macros and the two related functions:
>>>
>>> BLOCK: Denotes a lexical scope.  Contains BLOCK_VARS of variables
>>> declared in it, BLOCK_SUBBLOCKS of scopes nested in it, and
>>> BLOCK_CHAIN pointing to the next BLOCK.  Its BLOCK_SUPERCONTEXT
>>> point to the BLOCK of the enclosing scope.  May have
>>> a BLOCK_ABSTRACT_ORIGIN and a BLOCK_SOURCE_LOCATION.
>>>
>>> BLOCK_SUPERCONTEXT: The scope of the enclosing block, or FUNCTION_DECL
>>> for the "outermost" function scope.  Inlined functions are chained by
>>> this so that given expression E and its TREE_BLOCK(E) B,
>>> BLOCK_SUPERCONTEXT(B) is the scope (BLOCK) in which E has been made
>>> or into which E has been inlined.  In the latter case,
>>>
>>> BLOCK_ORIGIN(B) evaluates either to the enclosing BLOCK or to
>>> the enclosing function DECL.  It's never null.
>>>
>>> BLOCK_ABSTRACT_ORIGIN(B) is the FUNCTION_DECL of the function into
>>> which it has been inlined, or null if B is not inlined.
>>
>> It's the BLOCK or FUNCTION it was inlined _from_, not were it was 
>> inlined to.
>> It's the "ultimate" source, thus the abstract copy of the block or 
>> function decl
>> (for the outermost scope, aka inlined_function_outer_scope_p).  It 
>> corresponds
>> to what you'd expect for the DWARF abstract origin.
> 
> Thanks for the correction!  It's just the "innermost" block that
> points to the "ultimate" destination into which it's been inlined.
> 
>>
>> BLOCK_ABSTRACT_ORIGIN can be NULL (in case it isn't an inline instance).
>>
>>> BLOCK_ABSTRACT_ORIGIN: A BLOCK, or FUNCTION_DECL of the function
>>> into which a block has been inlined.  In a BLOCK immediately enclosing
>>> an inlined leaf expression points to the outermost BLOCK into which it
>>> has been inlined (thus bypassing all intermediate BLOCK_SUPERCONTEXTs).
>>>
>>> BLOCK_FRAGMENT_ORIGIN: ???
>>> BLOCK_FRAGMENT_CHAIN: ???
>>
>> that's for scope blocks split by hot/cold partitioning and only 
>> temporarily
>> populated.
> 
> Thanks, I now see these documented in detail in tree.h.
> 
>>
>>> bool inlined_function_outer_scope_p(BLOCK)   [tree.h]
>>>     Returns true if a BLOCK has a source location.
>>>     True for all but the innermost (no SUBBLOCKs?) and outermost blocks
>>>     into which an expression has been inlined. (Is this always true?)
>>>
>>> tree block_ultimate_origin(BLOCK)   [tree.c]
>>>     Returns BLOCK_ABSTRACT_ORIGIN(BLOCK), AO, after asserting that
>>>     (DECL_P(AO) && DECL_ORIGIN(AO) == AO) || BLOCK_ORIGIN(AO) == AO).
> 
> The attached diff adds the comments above to tree.h.
> 
> I looked for a good place in the manual to add the same text but I'm
> not sure.  Would the Blocks @subsection in generic.texi be appropriate?
> 
> Martin