diff mbox

Add gimple subclasses for every gimple code (was Re: [PATCH 0/6] Conversion of gimple types to C++ inheritance (v3))

Message ID 1383671947.5282.93.camel@surprise
State New
Headers show

Commit Message

David Malcolm Nov. 5, 2013, 5:19 p.m. UTC 
On Fri, 2013-11-01 at 17:36 -0400, Andrew MacLeod wrote:
> On 10/31/2013 12:26 PM, David Malcolm wrote:
> > [Shamelessly hijacking Andrew's thread about gimple.h refactoring,
> > since this seems on-topic for that, and I'm keen to hear from Andrew on
> > how the following would interact with his work - I *think* our two
> > cleanups are orthogonal.
> 
> Mostly orthogonal anyway... just stomping on the same bits :-).
> 
> Since you hijacked a planning thread, do you plan to take this any 
> further, or make this change and move on to something else?
> 
> It is a start, but it doesnt do the rest of the work that needs doing to 
> really take advantage of it... which will be extensive.
> for instance, we should change:
> 
>    static inline void
> ! gimple_call_set_lhs (gimple gs, tree lhs)
>    {
> -   GIMPLE_CHECK (gs, GIMPLE_CALL);
>      gimple_set_op (gs, 0, lhs);
> to
>      static inline void
> ! gimple_call_set_lhs (gimple_statement_call *gs, tree lhs)
>    {
>      gimple_set_op (gs, 0, lhs);
> 
> 
> but then every location that calls it needs an appropriate change:
> 
> !       gimple call;
> !       call = gimple_build_call_vec (build_fold_addr_expr_loc (0, 
> alias), vargs);
>          gimple_call_set_lhs (call, atree);
> 
> --- 1518,1524 ----
> 
> !       gimple_statement_call *call;
> !       call = as_a<gimple_statement_call> (gimple_build_call_vec 
> (build_fold_addr_expr_loc (0, alias), vargs));
>          gimple_call_set_lhs (call, atree);
> 
> And in fact there is a ripple effect to then change 
> gimple_build_call_vec to simply return a gimple_statement_call *... Then 
> this doesn't look as ugly either...
> 
> !       gimple_statement_call *call;
> !       call = gimple_build_call_vec (build_fold_addr_expr_loc (0, 
> alias), vargs);
>          gimple_call_set_lhs (call, atree);
> 
> that is looking much better :-)
> 
> 
> Leaving the names as they are should be ok, but the I'd also add a 
> typedef for the pointer without the 'statement' in the name.. ie
>      typedef gimple_statement_call *gimple_call;
> That seems in line with what we do with 'gimple' right now and the short 
> form is the type we'd normally use.
> 
> That adds a touch of difficulty with "as_a", since that requires the 
> type name, not the shorthand pointer.... so you have something like
> gimple_call call = as_a <gimple_statement_call> blah().
> I think as the changes to use the gimple_call type are pushed through 
> all the callers and callee's, the requirement of as_a and the long name 
> being ugly begins to rapidly disappear...  it'll only exist in the core 
> creation routines and no one will usually see it.   So I don't *think* 
> this is an issue...  but it is an ugly transition if its only partially 
> done.
> 
> And eventually we can pull the accessor routines and others into the 
> class itself:
>         gimple_call call;
>         call = gimple_build_call_vec (build_fold_addr_expr_loc (0, 
> alias), vargs);
>         call->set_lhs (atree);
> 
> Which results in a similar feel to the new gimple_type, gimple_decl, 
> etc. classes with my upcoming tree wrappers.  Changing gimple statements 
> to behave something like this is actually mentioned in the plan, but out 
> in the future once trees have been taken care of.
> 
> I would also plan to create instances for each of the gimple statements 
> that don't have them now, like gimple_statement_assign. Its lumped in as 
> a general GSS_WITH_MEM_OPS, so there is no gimple_statement_assign 
> class/struct to use.
> 
> It would really be nice to use the DEFGSCODE macro and gimple.def to 
> make this happen automagically somehow... Its tantalizingly close now I 
> think, especially combined with the info in gsstruct.def... Although if 
> we are moving to proper classes eventually its probably better to 
> explicitly write the required class for a statement kind.
> 
> That all said, this change enables that work to proceed if someone wants 
> to do it.
> 
> My question is: Is anyone going to do it, and if so,  who and when? :-)

Here's a followup patch which ensures that every gimple code has its own
subclass, by adding empty subclasses derived from the GSS_-based
subclasses as appropriate (I don't bother for gimple codes that already
have their own subclass due to having their own GSS layout).  I also
copied the comments from gimple.def into gimple.h, so that Doxygen picks
up on the descriptions and uses them to describe each subclass.

Posting for discussion (i.e. am still bootstrapping this; it also needs
the gengtype fix posted as
http://gcc.gnu.org/ml/gcc-patches/2013-11/msg00425.html)

You can see what the resulting gimple class hierarchy (as reported by
Doxygen) looks like here:
http://dmalcolm.fedorapeople.org/gcc/2013-11-05/doxygen/html/structgimple__statement__base.html

Comments

Michael Matz Nov. 6, 2013, 3:32 p.m. UTC | #1 
Hi,

On Tue, 5 Nov 2013, David Malcolm wrote:

> Here's a followup patch which ensures that every gimple code has its own
> subclass, by adding empty subclasses derived from the GSS_-based
> subclasses as appropriate (I don't bother for gimple codes that already
> have their own subclass due to having their own GSS layout).  I also
> copied the comments from gimple.def into gimple.h, so that Doxygen picks
> up on the descriptions and uses them to describe each subclass.

I don't like that.  The empty classes are just useless, they imply a 
structure that isn't really there, some of the separate gimple codes are 
basically selectors of specific subtypes of a generic concept, without 
additional data or methods; creating a type for those is confusing.

Generally I don't like complicating the type system without good reasons 
(as in actually also making use of the complicated types).  The fewer 
types the better IMO.


Ciao,
Michael.
David Malcolm Nov. 7, 2013, 4:56 a.m. UTC | #2 
On Wed, 2013-11-06 at 16:32 +0100, Michael Matz wrote:
> Hi,
> 
> On Tue, 5 Nov 2013, David Malcolm wrote:
> 
> > Here's a followup patch which ensures that every gimple code has its own
> > subclass, by adding empty subclasses derived from the GSS_-based
> > subclasses as appropriate (I don't bother for gimple codes that already
> > have their own subclass due to having their own GSS layout).  I also
> > copied the comments from gimple.def into gimple.h, so that Doxygen picks
> > up on the descriptions and uses them to describe each subclass.
> 
> I don't like that.  The empty classes are just useless, they imply a 
> structure that isn't really there, some of the separate gimple codes are 
> basically selectors of specific subtypes of a generic concept, without 
> additional data or methods; creating a type for those is confusing.

A type system does more than just express memory layouts:
* it permits the proof of absence of certain bugs
* it supports abstraction
* it documents the intent of the code

To give an example from the patch, the proposed gimple_statement_switch
subclass of gimple_statement_with_ops adds no extra fields, but it adds
the invariant that (assuming the ptr is non-NULL), that code ==
GIMPLE_SWITCH, or, more intuitively, "it's a switch statement".

This means that if we have a gimple_statement_switch, that both a human
reading the code and the compiler can "know" at compile-time that the
code == GIMPLE_SWITCH. 

The accessors are the big use-case for this, which would be a large
patch (as discussed elsewhere in the thread), but there are other places
where this could be used.

Consider tree-switch-conversion.c: this contains various "gimple"
variables but they don't work on arbitrary gimple; they require code ==
GIMPLE_SWITCH:

For example:
/* Collect information about GIMPLE_SWITCH statement SWTCH into INFO.
*/

static void
collect_switch_conv_info (gimple swtch, struct switch_conv_info *info)
{...}

Right now we're expressing the code == GIMPLE_SWITCH invariant via
naming-conventions ("swtch") and runtime checking in the checked build
(covering documentation of intent and implementation respectively).

We could be doing this directly in the type system, and using the
compiler to check it.

> Generally I don't like complicating the type system without good reasons 
> (as in actually also making use of the complicated types).

I can post a followup patch that makes use of each of these, if it will
help.

>   The fewer 
> types the better IMO.

There's a reductio ad absurdum of that argument: reduce the number of
types to zero and use void* everywhere, replacing field lookups with
pointer arithmetic and casts [1].  Obviously this is a strawman, but
looking through tree(-core).h, gimple.h and rtl.h it feels to me all too
reminiscent of the current implementation, alas.

Hope this is constructive.
Dave

[1] or cons cells if you're that way inclined.
Jeff Law Nov. 7, 2013, 5:32 a.m. UTC | #3 
[ Just a note, of this reply is meant for Michael and other parts for 
David, hopefully the audience is clear from the context. ]

On 11/06/13 21:56, David Malcolm wrote:
> On Wed, 2013-11-06 at 16:32 +0100, Michael Matz wrote:
>> Hi,
>>
>> On Tue, 5 Nov 2013, David Malcolm wrote:
>>
>>> Here's a followup patch which ensures that every gimple code has its own
>>> subclass, by adding empty subclasses derived from the GSS_-based
>>> subclasses as appropriate (I don't bother for gimple codes that already
>>> have their own subclass due to having their own GSS layout).  I also
>>> copied the comments from gimple.def into gimple.h, so that Doxygen picks
>>> up on the descriptions and uses them to describe each subclass.
>>
>> I don't like that.  The empty classes are just useless, they imply a
>> structure that isn't really there, some of the separate gimple codes are
>> basically selectors of specific subtypes of a generic concept, without
>> additional data or methods; creating a type for those is confusing.
>
> A type system does more than just express memory layouts:
> * it permits the proof of absence of certain bugs
Right.  As you have probably surmised, this is the single biggest thing 
we get from this work in my mind.  We use the type system to ensure a 
certain class of bugs simply won't get through the compilation phase.

That's a significant and important change from where we are now.  Right 
now we have no way of knowing that at compile time.  Instead we rely 
upon an insane set of macros to check this kind of invariant at run 
time.  Note carefully just because we don't hit a checking failure 
doesn't mean the code is safe.  It just means we haven't found a set of 
preconditions necessary to trip the problem at runtime.  Obviously in 
some (many), where may be no such way to trigger the failure, but 
there's no way to prove it.

Don't get me wrong the checking macros, when they were introduced were a 
godsend.  But they're papering over a fundamental problems in GCC's 
internal representations.

I think it's hard to overestimate the value we get by moving this stuff 
into compile-time type checking.


> I can post a followup patch that makes use of each of these, if it will
> help.
I wouldn't mind seeing a small example proof of concept posted to help 
those who don't see where this is going understand the goal.  I would 
recommend against posting another large patch for inclusion at this time.

Jeff
Michael Matz Nov. 7, 2013, 2:42 p.m. UTC | #4 
Hi,

On Wed, 6 Nov 2013, David Malcolm wrote:

> > I don't like that.  The empty classes are just useless, they imply a 
> > structure that isn't really there, some of the separate gimple codes 
> > are basically selectors of specific subtypes of a generic concept, 
> > without additional data or methods; creating a type for those is 
> > confusing.
> 
> A type system does more than just express memory layouts:

I know all that.  But there's a point on the scale from a void* type 
system to a different-type-for-everything system where the advantages of a 
more complex type system are anulled by the disadvantages of a more 
complex type system.  And I'm merely of the opinion that you crossed that 
point with this separation.

You know we could have a typesystem where every different natural number 
is a type (and with C++ we _really_ could do that).  Obviously that's also 
a reductio ad absurdum, but it demonstrates the point that there _are_ 
type systems with a too low complexity to expressiveness ratio.

> * it permits the proof of absence of certain bugs
> * it supports abstraction
> * it documents the intent of the code

Well, yes.  You can document code with other things than types, you can 
add abstractions via different means, and certain bugs can indeed only be 
ruled out by different static types.

In my mind types should abstract different larger concepts foremost (and 
not every little aspect of a concept).  Only _then_ should they be used 
for other effects like the above, and only if the disadvantages don't 
overshadow that.  Disadvantages being mostly simply more complexity: which 
types relate to others in which way; what are the methods you can do with 
that but not the other type; which are the members of the 100 types there 
are (and if a type system is too large to be used only by IDEs with code 
completion, then it's too complex); and of course also simply having to 
write more text when you can't use the same gimple variable for several 
statements.

> To give an example from the patch, the proposed gimple_statement_switch
> subclass of gimple_statement_with_ops adds no extra fields, but it adds
> the invariant that (assuming the ptr is non-NULL), that code ==
> GIMPLE_SWITCH, or, more intuitively, "it's a switch statement".
> 
> This means that if we have a gimple_statement_switch, that both a human
> reading the code and the compiler can "know" at compile-time that the
> code == GIMPLE_SWITCH. 

But a gimple switch is actually a special case of a gimple conditional 
jump (the normal GIMPLE_COND being another) which itself is a special 
case of a gimple control transfer (a thing causing one or multiple 
outgoing edges and ending a basic block).  That enlightens that your 
hierarchy might not actually be the best split of types, it's merely a 
formal translation of gimple codes into types.

And I question exactly that automatic introduction of types.  There's not 
enough human thought put into the hierarchy to warrant the change.  Types 
are a fundament and they shouldn't be introduced lightly.  As gimple codes 
are simply flat it doesn't matter so much that the inherent structure of 
gimple statements isn't reflected (although there _is_ some structure by 
having the with_ops and with_mem_ops codes be together).  But for a _type 
hierarchy_ I would pretty much require that real thought and insights are 
put into it.

> Consider tree-switch-conversion.c: this contains various "gimple"
> variables but they don't work on arbitrary gimple; they require code ==
> GIMPLE_SWITCH:
> ...
> We could be doing this directly in the type system, and using the
> compiler to check it.

Then please do that while introducing one new type.

> >   The fewer 
> > types the better IMO.
> 
> There's a reductio ad absurdum of that argument:

See above for my variant of that showing that it also goes into the other 
direction of more types.


Ciao,
Michael.
P.S.: And do away with the "_statement" part of the type, gimple_switch 
ought to be enough.
Alec Teal Nov. 7, 2013, 10:43 p.m. UTC | #5 
Hello

On 06/11/13 15:32, Michael Matz wrote:
> Hi,
>
> On Tue, 5 Nov 2013, David Malcolm wrote:
>
>> Here's a followup patch which ensures that every gimple code has its own
>> subclass, by adding empty subclasses derived from the GSS_-based
>> subclasses as appropriate (I don't bother for gimple codes that already
>> have their own subclass due to having their own GSS layout).  I also
>> copied the comments from gimple.def into gimple.h, so that Doxygen picks
>> up on the descriptions and uses them to describe each subclass.
> I don't like that.  The empty classes are just useless, they imply a
> structure that isn't really there, some of the separate gimple codes are
> basically selectors of specific subtypes of a generic concept, without
> additional data or methods; creating a type for those is confusing.
>
> Generally I don't like complicating the type system without good reasons
> (as in actually also making use of the complicated types).  The fewer
> types the better IMO.
How would you do this? The types are different even if there is no 
actual difference, much like there are different gimple codes in the 
first place.
He is trying to create a bijection between what we did have and what we 
now have so nothing breaks.
>
>
> Ciao,
> Michael.
Michael Matz Nov. 8, 2013, 2:14 p.m. UTC | #6 
Hi,

On Thu, 7 Nov 2013, Alec Teal wrote:

> > > subclass, by adding empty subclasses derived from the GSS_-based
> > > subclasses as appropriate (I don't bother for gimple codes that already
> > > have their own subclass due to having their own GSS layout).  I also
> > > copied the comments from gimple.def into gimple.h, so that Doxygen picks
> > > up on the descriptions and uses them to describe each subclass.
> > I don't like that.  The empty classes are just useless, they imply a
> > structure that isn't really there, some of the separate gimple codes are
> > basically selectors of specific subtypes of a generic concept, without
> > additional data or methods; creating a type for those is confusing.
> > 
> > Generally I don't like complicating the type system without good reasons
> > (as in actually also making use of the complicated types).  The fewer
> > types the better IMO.
> How would you do this?

How would I do what?  Making use of new types?  Well, like the opportunity 
that David already identified in tree-switching, I'd introduce the new 
type together with a patch to that pass to make use of it.  Further I'd 
try to think about how that new type represents a concept, how that would 
be generalized, and how it would fit in a really designed type hierarchy 
of gimple statements.  Then I would try to think about interaction of 
those new types with others we already have, in particular containers 
(should those become specialized as well?  I would say no from my gut, but 
that question does need some pondering).

> The types are different even if there is no actual difference, much like 
> there are different gimple codes in the first place. He is trying to 
> create a bijection between what we did have and what we now have

Yes, I understood that, and that's IMO the wrong way to introduce new 
types.  It really deserves some more than "we have these dozen gimple 
codes, let's create a dozen new types".  So, while a bijection between 
codes and types is simple to create, I'm pretty sure that's not the best 
mapping.

> so nothing breaks.

Currently nothing is broken, so that's certainly not the reason to 
introduce new types.


Ciao,
Michael.
diff mbox

Patch

commit ec6a05ed9ff15b4fc458c668cfd5227a1506042b
Author: David Malcolm <dmalcolm@redhat.com>
Date:   Tue Nov 5 04:30:15 2013 -0500

    Ensure every gimple code has a subclasses; document.
    
    Add empty subclasses to gimple.h as appropriate to ensure that every
    gimple code has its own gimple subclass.
    
    Add a copy of the documentation from gimple.def to every gimple subclass
    in gimple.h (both new and existing ones) so that the per-code documentation
    shows up per-class within Doxygen-generated docs.
    
    gcc/
    
    	* gimple.h (struct gimple_statement_error_mark): New subclass of
    	gimple_statement_base.
    	(struct gimple_statement_cond): New subclass of
    	gimple_statement_with_ops.
    	(struct gimple_statement_debug): New subclass of
    	gimple_statement_with_ops.
    	(gimple_statement_goto): New subclass of gimple_statement_with_ops.
    	(gimple_statement_label): New subclass of gimple_statement_with_ops.
    	(gimple_statement_switch): New subclass of
    	gimple_statement_with_ops.
    	(gimple_statement_assign): New subclass of
    	gimple_statement_with_memory_ops.
    	(gimple_statement_call): Add documentation from gimple.def.
    	(gimple_statement_bind): Likewise.
    	(gimple_statement_catch): Likewise.
    	(gimple_statement_eh_filter): Likewise.
    	(gimple_statement_eh_else): Likewise.
    	(gimple_statement_eh_mnt): Likewise.
    	(gimple_statement_phi): Likewise.
    	(gimple_statement_resx): New subclass of gimple_statement_eh_ctrl.
    	(gimple_statement_dispatch): Likewise.
    	(gimple_statement_try): Add documentation from gimple.def.
    	(gimple_statement_nop): New subclass of gimple_statement_base.
    	(gimple_statement_wce): Add documentation from gimple.def.
    	(gimple_statement_asm): Likewise.
    	(gimple_statement_omp_critical): Likewise.
    	(gimple_statement_omp_for): Likewise.
    	(gimple_statement_omp_master): New subclass of gimple_statement_omp.
    	(gimple_statement_omp_taskgroup): Likewise.
    	(gimple_statement_omp_ordered): Likewise.
    	(gimple_statement_omp_parallel): Add documentation from
    	gimple.def.
    	(gimple_statement_omp_task): Likewise.
    	(gimple_statement_omp_section): New subclass of
    	gimple_statement_omp.
    	(gimple_statement_omp_sections): Add documentation from gimple.def.
    	(gimple_statement_omp_sections_switch): New subclass of
    	gimple_statement_base.
    	(gimple_statement_omp_continue): Add documentation from gimple.def.
    	(gimple_statement_omp_target): New subclass of
    	gimple_statement_omp_parallel.
    	(gimple_statement_omp_teams): New subclass of
    	gimple_statement_omp_single.
    	(gimple_predict): New subclass of gimple_statement_base.
    	(gimple_statement_omp_atomic_load): Add documentation from
    	gimple.def.
    	(gimple_statement_omp_atomic_store): Update comment.
    	(gimple_statement_omp_return): New subclass of
    	gimple_statement_omp_atomic_store.
    	(gimple_statement_transaction): Add documentation from gimple.def.
    	(gimple_statement_return): New subclass of
    	gimple_statement_with_memory_ops.

diff --git a/gcc/gimple.h b/gcc/gimple.h
index 35bfa06..318953c 100644
--- a/gcc/gimple.h
+++ b/gcc/gimple.h
@@ -223,6 +223,13 @@  struct GTY((desc ("gimple_statement_structure (&%h)"), tag ("GSS_BASE"),
   gimple GTY((skip)) prev;
 };
 
+/* code == GIMPLE_ERROR_MARK, an error marker.  */
+
+struct GTY(())
+  gimple_statement_error_mark : public gimple_statement_base
+{
+  /* no additional fields; this uses the layout for GSS_BASE. */
+};
 
 /* Base structure for tuples with operands.  */
 
@@ -255,6 +262,81 @@  struct GTY((tag("GSS_WITH_OPS")))
   tree GTY((length ("%h.num_ops"))) op[1];
 };
 
+/* code == GIMPLE_COND:
+
+   GIMPLE_COND <COND_CODE, OP1, OP2, TRUE_LABEL, FALSE_LABEL>
+   represents the conditional jump:
+
+   if (OP1 COND_CODE OP2) goto TRUE_LABEL else goto FALSE_LABEL
+
+   COND_CODE is the tree code used as the comparison predicate.  It
+   must be of class tcc_comparison.
+
+   OP1 and OP2 are the operands used in the comparison.  They must be
+   accepted by is_gimple_operand.
+
+   TRUE_LABEL and FALSE_LABEL are the LABEL_DECL nodes used as the
+   jump target for the comparison.  */
+
+struct GTY(())
+  gimple_statement_cond : public gimple_statement_with_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_OPS. */
+};
+
+/* code == GIMPLE_DEBUG, a debug statement.  */
+
+struct GTY(())
+  gimple_statement_debug : public gimple_statement_with_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_OPS. */
+};
+
+/* code == GIMPLE_GOTO
+
+   GIMPLE_GOTO <TARGET> represents unconditional jumps.
+   TARGET is a LABEL_DECL or an expression node for computed GOTOs.  */
+
+struct GTY(())
+  gimple_statement_goto : public gimple_statement_with_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_OPS. */
+};
+
+/* code == GIMPLE_LABEL
+
+   GIMPLE_LABEL <LABEL> represents label statements.  LABEL is a
+   LABEL_DECL representing a jump target.  */
+
+struct GTY(())
+  gimple_statement_label : public gimple_statement_with_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_OPS. */
+};
+
+/* code == GIMPLE_SWITCH
+
+   GIMPLE_SWITCH <INDEX, DEFAULT_LAB, LAB1, ..., LABN> represents the
+   multiway branch:
+
+   switch (INDEX)
+   {
+     case LAB1: ...; break;
+     ...
+     case LABN: ...; break;
+     default: ...
+   }
+
+   INDEX is the variable evaluated to decide which label to jump to.
+
+   DEFAULT_LAB, LAB1 ... LABN are the tree nodes representing case labels.
+   They must be CASE_LABEL_EXPR nodes.  */
+
+struct GTY(())
+  gimple_statement_switch : public gimple_statement_with_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_OPS. */
+};
 
 /* Base for statements that take both memory and register operands.  */
 
@@ -286,8 +368,49 @@  struct GTY((tag("GSS_WITH_MEM_OPS")))
   tree GTY((length ("%h.num_ops"))) op[1];
 };
 
+/* code == GIMPLE_ASSIGN:
+
+   GIMPLE_ASSIGN <SUBCODE, LHS, RHS1[, RHS2]> represents the assignment
+   statement
+
+   LHS = RHS1 SUBCODE RHS2.
+
+   SUBCODE is the tree code for the expression computed by the RHS of the
+   assignment.  It must be one of the tree codes accepted by
+   get_gimple_rhs_class.  If LHS is not a gimple register according to
+   is_gimple_reg, SUBCODE must be of class GIMPLE_SINGLE_RHS.
+
+   LHS is the operand on the LHS of the assignment.  It must be a tree node
+   accepted by is_gimple_lvalue.
+
+   RHS1 is the first operand on the RHS of the assignment.  It must always be
+   present.  It must be a tree node accepted by is_gimple_val.
+
+   RHS2 is the second operand on the RHS of the assignment.  It must be a tree
+   node accepted by is_gimple_val.  This argument exists only if SUBCODE is
+   of class GIMPLE_BINARY_RHS.  */
+
+struct GTY(())
+  gimple_statement_assign : public gimple_statement_with_memory_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_MEM_OPS. */
+};
+
+
+/* code == GIMPLE_CALL.
+
+   GIMPLE_CALL <FN, LHS, ARG1, ..., ARGN[, CHAIN]> represents function
+   calls.
+
+   FN is the callee.  It must be accepted by is_gimple_call_addr.
 
-/* Call statements that take both memory and register operands.  */
+   LHS is the operand where the return value from FN is stored.  It may
+   be NULL.
+
+   ARG1 ... ARGN are the arguments.  They must all be accepted by
+   is_gimple_operand.
+
+   CHAIN is the optional static chain link for nested functions.  */
 
 struct GTY((tag("GSS_CALL")))
   gimple_statement_call : public gimple_statement_with_memory_ops_base
@@ -324,7 +447,12 @@  struct GTY((tag("GSS_OMP")))
 };
 
 
-/* GIMPLE_BIND */
+/* code == GIMPLE_BIND:
+
+   GIMPLE_BIND <VARS, BLOCK, BODY> represents a lexical scope.
+   VARS is the set of variables declared in that scope.
+   BLOCK is the symbol binding block used for debug information.
+   BODY is the sequence of statements in the scope.  */
 
 struct GTY((tag("GSS_BIND")))
   gimple_statement_bind : public gimple_statement_base
@@ -348,7 +476,11 @@  struct GTY((tag("GSS_BIND")))
 };
 
 
-/* GIMPLE_CATCH */
+/* code == GIMPLE_CATCH:
+
+   GIMPLE_CATCH <TYPES, HANDLER> represents a typed exception handler.
+   TYPES is the type (or list of types) handled.  HANDLER is the
+   sequence of statements that handle these types.  */
 
 struct GTY((tag("GSS_CATCH")))
   gimple_statement_catch : public gimple_statement_base
@@ -363,7 +495,11 @@  struct GTY((tag("GSS_CATCH")))
 };
 
 
-/* GIMPLE_EH_FILTER */
+/* code == GIMPLE_EH_FILTER:
+
+   GIMPLE_EH_FILTER <TYPES, FAILURE> represents an exception
+   specification.  TYPES is a list of allowed types and FAILURE is the
+   sequence of statements to execute on failure.  */
 
 struct GTY((tag("GSS_EH_FILTER")))
   gimple_statement_eh_filter : public gimple_statement_base
@@ -379,7 +515,12 @@  struct GTY((tag("GSS_EH_FILTER")))
   gimple_seq failure;
 };
 
-/* GIMPLE_EH_ELSE */
+/* code == GIMPLE_EH_ELSE:
+
+   GIMPLE_EH_ELSE <N_BODY, E_BODY> must be the sole contents of
+   a GIMPLE_TRY_FINALLY node.  For all normal exits from the try block,
+   N_BODY is run; for all exception exits from the try block,
+   E_BODY is run.  */
 
 struct GTY((tag("GSS_EH_ELSE")))
   gimple_statement_eh_else : public gimple_statement_base
@@ -390,7 +531,11 @@  struct GTY((tag("GSS_EH_ELSE")))
   gimple_seq n_body, e_body;
 };
 
-/* GIMPLE_EH_MUST_NOT_THROW */
+/* code == GIMPLE_EH_MUST_NOT_THROW:
+
+   GIMPLE_EH_MUST_NOT_THROW <DECL> represents an exception barrier.
+   DECL is a noreturn function decl taking no arguments that will
+   be invoked if an exception propagates to this point.  */
 
 struct GTY((tag("GSS_EH_MNT")))
   gimple_statement_eh_mnt : public gimple_statement_base
@@ -401,7 +546,18 @@  struct GTY((tag("GSS_EH_MNT")))
   tree fndecl;
 };
 
-/* GIMPLE_PHI */
+/* code == GIMPLE_PHI:
+
+   GIMPLE_PHI <RESULT, ARG1, ..., ARGN> represents the PHI node
+
+   RESULT = PHI <ARG1, ..., ARGN>
+
+   RESULT is the SSA name created by this PHI node.
+
+   ARG1 ... ARGN are the arguments to the PHI node.  N must be
+   exactly the same as the number of incoming edges to the basic block
+   holding the PHI node.  Every argument is either an SSA name or a
+   tree node of class tcc_constant.  */
 
 struct GTY((tag("GSS_PHI")))
   gimple_statement_phi : public gimple_statement_base
@@ -432,8 +588,43 @@  struct GTY((tag("GSS_EH_CTRL")))
   int region;
 };
 
+/* code == GIMPLE_RESX:
+
+   GIMPLE_RESX resumes execution after an exception.  */
+
+struct GTY(())
+  gimple_statement_resx : public gimple_statement_eh_ctrl
+{
+  /* no additional fields; this uses the layout for GSS_EH_CTRL. */
+};
+
+/* code == GIMPLE_EH_DISPATCH:
 
-/* GIMPLE_TRY */
+   GIMPLE_EH_DISPATCH demultiplexes an exception edge based on
+   the FILTER argument.  */
+
+struct GTY(())
+  gimple_statement_dispatch : public gimple_statement_eh_ctrl
+{
+  /* no additional fields; this uses the layout for GSS_EH_CTRL. */
+};
+
+
+/* code == GIMPLE_TRY:
+
+   GIMPLE_TRY <TRY_KIND, EVAL, CLEANUP>
+   represents a try/catch or a try/finally statement.
+
+   TRY_KIND is either GIMPLE_TRY_CATCH or GIMPLE_TRY_FINALLY.
+
+   EVAL is the sequence of statements to execute on entry to GIMPLE_TRY.
+
+   CLEANUP is the sequence of statements to execute according to
+   TRY_KIND.  If TRY_KIND is GIMPLE_TRY_CATCH, CLEANUP is only exected
+   if an exception is thrown during execution of EVAL.  If TRY_KIND is
+   GIMPLE_TRY_FINALLY, CLEANUP is always executed after executing EVAL
+   (regardless of whether EVAL finished normally, or jumped out or an
+   exception was thrown).  */
 
 struct GTY((tag("GSS_TRY")))
   gimple_statement_try : public gimple_statement_base
@@ -463,7 +654,24 @@  enum gimple_try_flags
   GIMPLE_TRY_CATCH_IS_CLEANUP = 1 << 2
 };
 
-/* GIMPLE_WITH_CLEANUP_EXPR */
+/* code == GIMPLE_NOP:
+
+   GIMPLE_NOP represents the "do nothing" statement.  */
+
+struct GTY(())
+  gimple_statement_nop : public gimple_statement_base
+{
+  /* no additional fields; this uses the layout for GSS_BASE. */
+};
+
+
+/* code == GIMPLE_WITH_CLEANUP_EXPR:
+
+   This node represents a cleanup expression.  It is ONLY USED INTERNALLY
+   by the gimplifier as a placeholder for cleanups, and its uses will be
+   cleaned up by the time gimplification is done.
+
+   This tuple should not exist outside of the gimplifier proper.  */
 
 struct GTY((tag("GSS_WCE")))
   gimple_statement_wce : public gimple_statement_base
@@ -481,7 +689,16 @@  struct GTY((tag("GSS_WCE")))
 };
 
 
-/* GIMPLE_ASM  */
+/* code == GIMPLE_ASM:
+
+   GIMPLE_ASM <STRING, I1, ..., IN, O1, ... OM, C1, ..., CP>
+   represents inline assembly statements.
+
+   STRING is the string containing the assembly statements.
+   I1 ... IN are the N input operands.
+   O1 ... OM are the M output operands.
+   C1 ... CP are the P clobber operands.
+   L1 ... LQ are the Q label operands.  */
 
 struct GTY((tag("GSS_ASM")))
   gimple_statement_asm : public gimple_statement_with_memory_ops_base
@@ -506,7 +723,13 @@  struct GTY((tag("GSS_ASM")))
   tree GTY((length ("%h.num_ops"))) op[1];
 };
 
-/* GIMPLE_OMP_CRITICAL */
+/* code == GIMPLE_OMP_CRITICAL:
+   GIMPLE_OMP_CRITICAL <NAME, BODY> represents
+
+   #pragma omp critical [name]
+
+   NAME is the name given to the critical section.
+   BODY is the sequence of statements that are inside the critical section.  */
 
 struct GTY((tag("GSS_OMP_CRITICAL")))
   gimple_statement_omp_critical : public gimple_statement_omp
@@ -536,7 +759,43 @@  struct GTY(()) gimple_omp_for_iter {
   tree incr;
 };
 
-/* GIMPLE_OMP_FOR */
+/* code == GIMPLE_OMP_FOR:
+
+   GIMPLE_OMP_FOR <BODY, CLAUSES, INDEX, INITIAL, FINAL, COND, INCR, PRE_BODY>
+   represents
+
+   PRE_BODY
+   #pragma omp for [clause1 ... clauseN]
+   for (INDEX = INITIAL; INDEX COND FINAL; INDEX {+=,-=} INCR)
+   BODY
+
+   BODY is the loop body.
+
+   CLAUSES is the list of clauses.
+
+   INDEX must be an integer or pointer variable, which is implicitly thread
+   private.  It must be accepted by is_gimple_operand.
+
+   INITIAL is the initial value given to INDEX. It must be
+   accepted by is_gimple_operand.
+
+   FINAL is the final value that INDEX should take. It must
+   be accepted by is_gimple_operand.
+
+   COND is the condition code for the controlling predicate.  It must
+   be one of { <, >, <=, >= }
+
+   INCR is the loop index increment.  It must be tree node of type
+   tcc_constant.
+
+   PRE_BODY is a landing pad filled by the gimplifier with things from
+   INIT, COND, and INCR that are technically part of the OMP_FOR
+   structured block, but are evaluated before the loop body begins.
+
+   INITIAL, FINAL and INCR are required to be loop invariant integer
+   expressions that are evaluated without any synchronization.
+   The evaluation order, frequency of evaluation and side-effects are
+   unspecified by the standard.  */
 
 struct GTY((tag("GSS_OMP_FOR")))
   gimple_statement_omp_for : public gimple_statement_omp
@@ -558,8 +817,58 @@  struct GTY((tag("GSS_OMP_FOR")))
   gimple_seq pre_body;
 };
 
+/* code == GIMPLE_OMP_MASTER:
+
+   GIMPLE_OMP_MASTER <BODY> represents #pragma omp master.
+   BODY is the sequence of statements to execute in the master section.  */
+
+struct GTY(())
+  gimple_statement_omp_master : public gimple_statement_omp
+{
+  /* no additional fields; this uses the layout for GSS_OMP.  */
+};
+
+/* code == GIMPLE_OMP_TASKGROUP:
+
+   GIMPLE_OMP_TASKGROUP <BODY> represents #pragma omp taskgroup.
+   BODY is the sequence of statements to execute in the taskgroup section.  */
+
+struct GTY(())
+  gimple_statement_omp_taskgroup : public gimple_statement_omp
+{
+  /* no additional fields; this uses the layout for GSS_OMP.  */
+};
+
+/* code == GIMPLE_OMP_ORDERED:
 
-/* GIMPLE_OMP_PARALLEL */
+   GIMPLE_OMP_ORDERED <BODY> represents #pragma omp ordered.
+   BODY is the sequence of statements to execute in the ordered section.  */
+
+struct GTY(())
+  gimple_statement_omp_ordered : public gimple_statement_omp
+{
+  /* no additional fields; this uses the layout for GSS_OMP.  */
+};
+
+
+/* code == GIMPLE_OMP_PARALLEL:
+
+   GIMPLE_OMP_PARALLEL <BODY, CLAUSES, CHILD_FN, DATA_ARG> represents
+
+   #pragma omp parallel [CLAUSES]
+   BODY
+
+   BODY is a the sequence of statements to be executed by all threads.
+
+   CLAUSES is an OMP_CLAUSE chain with all the clauses.
+
+   CHILD_FN is set when outlining the body of the parallel region.
+   All the statements in BODY are moved into this newly created
+   function when converting OMP constructs into low-GIMPLE.
+
+   DATA_ARG is a local variable in the parent function containing data
+   to be shared with CHILD_FN.  This is used to implement all the data
+   sharing clauses.  */
 
 struct GTY((tag("GSS_OMP_PARALLEL")))
   gimple_statement_omp_parallel : public gimple_statement_omp
@@ -580,7 +889,33 @@  struct GTY((tag("GSS_OMP_PARALLEL")))
 };
 
 
-/* GIMPLE_OMP_TASK */
+/* code == GIMPLE_OMP_TASK:
+
+   GIMPLE_OMP_TASK <BODY, CLAUSES, CHILD_FN, DATA_ARG, COPY_FN,
+		    ARG_SIZE, ARG_ALIGN> represents
+
+   #pragma omp task [CLAUSES]
+   BODY
+
+   BODY is a the sequence of statements to be executed by all threads.
+
+   CLAUSES is an OMP_CLAUSE chain with all the clauses.
+
+   CHILD_FN is set when outlining the body of the explicit task region.
+   All the statements in BODY are moved into this newly created
+   function when converting OMP constructs into low-GIMPLE.
+
+   DATA_ARG is a local variable in the parent function containing data
+   to be shared with CHILD_FN.  This is used to implement all the data
+   sharing clauses.
+
+   COPY_FN is set when outlining the firstprivate var initialization.
+   All the needed statements are emitted into the newly created
+   function, or when only memcpy is needed, it is NULL.
+
+   ARG_SIZE and ARG_ALIGN are the size and alignment of the incoming
+   data area allocated by GOMP_task and passed to CHILD_FN.  */
+
 
 struct GTY((tag("GSS_OMP_TASK")))
   gimple_statement_omp_task : public gimple_statement_omp_parallel
@@ -597,12 +932,25 @@  struct GTY((tag("GSS_OMP_TASK")))
   tree arg_align;
 };
 
+/* code == GIMPLE_OMP_SECTION:
+
+   OMP_SECTION <BODY> represents #pragma omp section.
+   BODY is the sequence of statements in the section body.  */
 
-/* GIMPLE_OMP_SECTION */
-/* Uses struct gimple_statement_omp.  */
+struct GTY(())
+  gimple_statement_omp_section : public gimple_statement_omp
+{
+  /* no additional fields; this uses the layout for GSS_OMP. */
+};
 
+/* code == GIMPLE_OMP_SECTIONS:
 
-/* GIMPLE_OMP_SECTIONS */
+   OMP_SECTIONS <BODY, CLAUSES, CONTROL> represents #pragma omp sections.
+
+   BODY is the sequence of statements in the sections body.
+   CLAUSES is an OMP_CLAUSE chain holding the list of associated clauses.
+   CONTROL is a VAR_DECL used for deciding which of the sections
+   to execute.  */
 
 struct GTY((tag("GSS_OMP_SECTIONS")))
   gimple_statement_omp_sections : public gimple_statement_omp
@@ -618,10 +966,25 @@  struct GTY((tag("GSS_OMP_SECTIONS")))
   tree control;
 };
 
-/* GIMPLE_OMP_CONTINUE.
+/* code == GIMPLE_OMP_SECTIONS_SWITCH:
+
+   GIMPLE_OMP_SECTIONS_SWITCH is a marker placed immediately after
+   OMP_SECTIONS.  It represents the GIMPLE_SWITCH used to decide which
+   branch is taken.  */
+
+struct GTY(())
+  gimple_statement_omp_sections_switch : public gimple_statement_base
+{
+  /* no additional fields; this uses the layout for GSS_BASE. */
+};
+
+/* code == GIMPLE_OMP_CONTINUE:
 
    Note: This does not inherit from gimple_statement_omp, because we
-         do not need the body field.  */
+         do not need the body field.
+
+   GIMPLE_OMP_CONTINUE marks the location of the loop or sections
+   iteration in partially lowered OpenMP code.  */
 
 struct GTY((tag("GSS_OMP_CONTINUE")))
   gimple_statement_omp_continue : public gimple_statement_base
@@ -646,10 +1009,65 @@  struct GTY((tag("GSS_OMP_SINGLE")))
   tree clauses;
 };
 
+/* code == GIMPLE_OMP_TARGET:
+
+   GIMPLE_OMP_TARGET <BODY, CLAUSES, CHILD_FN> represents
+   #pragma omp target {,data,update}
+   BODY is the sequence of statements inside the target construct
+   (NULL for target update).
+   CLAUSES is an OMP_CLAUSE chain holding the associated clauses.
+   CHILD_FN is set when outlining the body of the target region.
+   All the statements in BODY are moved into this newly created
+   function when converting OMP constructs into low-GIMPLE.
+   DATA_ARG is a vec of 3 local variables in the parent function
+   containing data to be mapped to CHILD_FN.  This is used to
+   implement the MAP clauses.  */
+
+struct GTY(())
+  gimple_statement_omp_target : public gimple_statement_omp_parallel
+{
+  /* no additional fields; this uses the layout for GSS_OMP_PARALLEL. */
+};
+
+/* code == GIMPLE_OMP_TEAMS:
+
+   GIMPLE_OMP_TEAMS <BODY, CLAUSES> represents #pragma omp teams
+   BODY is the sequence of statements inside the single section.
+   CLAUSES is an OMP_CLAUSE chain holding the associated clauses.  */
+
+struct GTY(())
+  gimple_statement_omp_teams : public gimple_statement_omp_single
+{
+  /* no additional fields; this uses the layout for GSS_OMP_SINGLE. */
+};
+
+/* code = GIMPLE_PREDICT:
+
+   GIMPLE_PREDICT <PREDICT, OUTCOME> specifies a hint for branch prediction.
+
+   PREDICT is one of the predictors from predict.def.
+
+   OUTCOME is NOT_TAKEN or TAKEN.  */
 
-/* GIMPLE_OMP_ATOMIC_LOAD.
+struct GTY(())
+  gimple_predict : public gimple_statement_base
+{
+  /* no additional fields; this uses the layout for GSS_BASE. */
+};
+
+/* code == GIMPLE_OMP_ATOMIC_LOAD.
    Note: This is based on gimple_statement_base, not g_s_omp, because g_s_omp
-   contains a sequence, which we don't need here.  */
+   contains a sequence, which we don't need here.
+
+   Tuples used for lowering of OMP_ATOMIC.  Although the form of the OMP_ATOMIC
+   expression is very simple (just in form mem op= expr), various implicit
+   conversions may cause the expression to become more complex, so that it does
+   not fit the gimple grammar very well.  To overcome this problem, OMP_ATOMIC
+   is rewritten as a sequence of two codes in gimplification:
+
+   GIMPLE_OMP_LOAD (tmp, mem)
+   val = some computations involving tmp;
+   GIMPLE_OMP_STORE (val).  */
 
 struct GTY((tag("GSS_OMP_ATOMIC_LOAD")))
   gimple_statement_omp_atomic_load : public gimple_statement_base
@@ -660,7 +1078,8 @@  struct GTY((tag("GSS_OMP_ATOMIC_LOAD")))
   tree rhs, lhs;
 };
 
-/* GIMPLE_OMP_ATOMIC_STORE.
+/* code == GIMPLE_OMP_ATOMIC_STORE:
+
    See note on GIMPLE_OMP_ATOMIC_LOAD.  */
 
 struct GTY((tag("GSS_OMP_ATOMIC_STORE")))
@@ -672,6 +1091,16 @@  struct GTY((tag("GSS_OMP_ATOMIC_STORE")))
   tree val;
 };
 
+/* code == OMP_RETURN:
+
+   OMP_RETURN marks the end of an OpenMP directive.  */
+
+struct GTY(())
+  gimple_statement_omp_return : public gimple_statement_omp_atomic_store
+{
+  /* no additional fields; this uses the layout for GSS_OMP_ATOMIC_STORE.  */
+};
+
 /* GIMPLE_TRANSACTION.  */
 
 /* Bits to be stored in the GIMPLE_TRANSACTION subcode.  */
@@ -700,6 +1129,16 @@  struct GTY((tag("GSS_OMP_ATOMIC_STORE")))
    likely because it is guaranteed to go irrevocable upon entry.  */
 #define GTMA_HAS_NO_INSTRUMENTATION	(1u << 7)
 
+
+/* code == GIMPLE_TRANSACTION:
+
+   GIMPLE_TRANSACTION <BODY, LABEL> represents __transaction_atomic and
+   __transaction_relaxed blocks.
+   BODY is the sequence of statements inside the transaction.
+   LABEL is a label for the statement immediately following the
+   transaction.  This is before RETURN so that it has MEM_OPS,
+   so that it can clobber global memory.  */
+
 struct GTY((tag("GSS_TRANSACTION")))
   gimple_statement_transaction : public gimple_statement_with_memory_ops_base
 {
@@ -712,6 +1151,19 @@  struct GTY((tag("GSS_TRANSACTION")))
   tree label;
 };
 
+/* code == GIMPLE_RETURN:
+
+   GIMPLE_RETURN <RETVAL> represents return statements.
+
+   RETVAL is the value to return or NULL.  If a value is returned it
+   must be accepted by is_gimple_operand.  */
+
+struct GTY(())
+  gimple_statement_return : public gimple_statement_with_memory_ops
+{
+  /* no additional fields; this uses the layout for GSS_WITH_MEM_OPS. */
+};
+
 #define DEFGSSTRUCT(SYM, STRUCT, HAS_TREE_OP)	SYM,
 enum gimple_statement_structure_enum {
 #include "gsstruct.def"