Re: [RFC] Contributing tree-ssa to mainline

Re: [RFC] Contributing tree-ssa to mainline

[Richard Kenner]

    Expecting tree-ssa to produce code better by a factor of two is simply
    unreasonable.

In general, of course.  But if it is really allowing new classes of
optimizations to be performed (which was the argument to justify the new
infrastructure), it should be possible to construct test cases that show
that sort of performance improvement (factors of two or more).

Remember that the last time we had the discussion of the timing of tree-ssa,
people claimed it was "essential" for 3.5 since there was a tremendous
improvement on some C++ cases.  So let's see those cases.

Re: [RFC] Contributing tree-ssa to mainline

[Diego Novillo]

On Fri, 2004-01-16 at 22:24, Richard Kenner wrote:

> Remember that the last time we had the discussion of the timing of tree-ssa,
> people claimed it was "essential" for 3.5 since there was a tremendous
> improvement on some C++ cases.  So let's see those cases.
>
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747


Diego.

Re: [RFC] Contributing tree-ssa to mainline

[Per Bothner]

Diego Novillo wrote:

> On Fri, 2004-01-16 at 22:24, Richard Kenner wrote:
> 
> 
>>Remember that the last time we had the discussion of the timing of tree-ssa,
>>people claimed it was "essential" for 3.5 since there was a tremendous
>>improvement on some C++ cases.  So let's see those cases.
>>
> 
> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747

Can you give numbers?  I.e. how much faster does that (or a similar)
testcase run?  Have we met Kenner's 2x goal?
-- 
	--Per Bothner
per@bothner.com   http://per.bothner.com/

Re: [RFC] Contributing tree-ssa to mainline

[Andrew Pinski]

On Jan 16, 2004, at 21:52, Per Bothner wrote:

> Diego Novillo wrote:
>
>> On Fri, 2004-01-16 at 22:24, Richard Kenner wrote:
>>> Remember that the last time we had the discussion of the timing of 
>>> tree-ssa,
>>> people claimed it was "essential" for 3.5 since there was a 
>>> tremendous
>>> improvement on some C++ cases.  So let's see those cases.
>>>
>> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747
>
> Can you give numbers?  I.e. how much faster does that (or a similar)
> testcase run?  Have we met Kenner's 2x goal?

First it also improves C code also.
See PR 9540 for an example
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=9540

And PR 2806 for an example where the if combiner on the tree-ssa
beats the heck out of the one on the RTL level.
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=2806

Also PR 9566 where the problem is that GCC will put things on the stack 
too early.
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=9566

These can be any were between .5x and 10x depending on how big the 
struct is and if you
have large number of copies.

Also compile time for some testcases are much better, see PR 2692 for 
an example:
http://gcc.gnu.org/bugzilla/show_bug.cgi?id=2692

Also the stack sizes that most function needs is going be lowered by a 
significant amount in
most C++ cases.  There are many test cases in the bugzilla for this.

I think the tree-ssa is in good shape to be included in for 3.5 except 
for the current
problem of bootstrapping on some targets/building for some targets, 
these really should be
fixed before the merging should happen.

Thanks,
Andrew Pinski

Re: [RFC] Contributing tree-ssa to mainline

[Diego Novillo]

[-- Attachment #1: Type: text/plain, Size: 935 bytes --]

On Sat, 2004-01-17 at 00:52, Per Bothner wrote:
> Diego Novillo wrote:
> 
> > On Fri, 2004-01-16 at 22:24, Richard Kenner wrote:
> > 
> > 
> >>Remember that the last time we had the discussion of the timing of tree-ssa,
> >>people claimed it was "essential" for 3.5 since there was a tremendous
> >>improvement on some C++ cases.  So let's see those cases.
> >>
> > 
> > http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747
> 
> Can you give numbers?  I.e. how much faster does that (or a similar)
> testcase run?
>
Sure.  I added some of the missing bits in 12747's test program to make
it executable (attached).  The binary produced by mainline executes in
28.62 seconds.  The one produced by tree-ssa executes in 10.57 seconds
(average over 3 runs).

As with any benchmark, the fact that we do good here cannot be
extrapolated to any other random piece of code.

[ apologies to our C++ experts for butchering the test case. ]


Diego.

[-- Attachment #2: 12747.C --]
[-- Type: text/x-c++, Size: 2039 bytes --]

#include <string.h>
#include <stdlib.h>

class BitRef;

class BitVector
{
public:

    BitVector (unsigned nbits) : m_size(nbits)
      {
	m_data = (unsigned long *)malloc (m_size*sizeof(unsigned long));
      }

    BitVector (const BitVector &orig) : m_size (orig.size())
      {
	m_data = (unsigned long *)malloc (m_size*sizeof(unsigned long));
	memcpy(m_data,orig.m_data,m_size);
      }

    BitVector & operator= (const BitVector &orig)
      {
	m_size = orig.size();
	m_data = (unsigned long *)malloc (m_size*sizeof(unsigned long));
	memcpy(m_data,orig.m_data,m_size);
      }

   ~BitVector ()
     {
       free (m_data);
     }
  unsigned size () const
  {
    return m_size;
  }
  bool getBit (unsigned idx)
    {
      return m_data[idx] != 0;
    }

  void setBit (unsigned idx, bool value)
    {
      m_data[idx] = (unsigned long)value;
    }

  inline BitRef operator[] (unsigned idx);
//private:
  unsigned long *m_data;
  unsigned m_size;
};

class BitRef
{
public:
  BitRef (BitVector & bv, unsigned idx):m_bv (bv), m_idx (idx)
  {
  }
  bool value () const
  {
    return m_bv.getBit (m_idx);
  }
  operator  bool () const
  {
    return value ();
  }
  BitRef & operator= (bool newVal)
  {
    m_bv.setBit (m_idx, newVal);
    return *this;
  }
  BitRef & operator= (const BitRef & newVal)
  {
    m_bv.setBit (m_idx, newVal.value ());
    return *this;
  }
private:
  BitVector & m_bv;
  unsigned m_idx;
};

inline BitRef
BitVector::operator[] (unsigned idx)
{
  return BitRef (*this, idx);
}

// abstract copy: compiler should be able to make this as fast as copy_2
void
copy (BitVector & dest, BitVector & src)
{
  unsigned
    sz = dest.size ();
  for (unsigned i = 0; i < sz; i++)
    dest[i] = src[i];
}

// direct copy, without proxy objects.
void
copy_2 (BitVector & dest, BitVector & src)
{
  unsigned
    sz = dest.size ();
  for (unsigned i = 0; i < sz; i++)
    dest.setBit (i, src.getBit (i));
}

main()
{
  BitVector bv1(30000), bv2(30000);
  int i;

  for (i = 0; i < 50000; i++)
    copy (bv1, bv2);
}

Re: [RFC] Contributing tree-ssa to mainline

[Florian Weimer]

Diego Novillo wrote:

> On Fri, 2004-01-16 at 22:24, Richard Kenner wrote:
> 
> > Remember that the last time we had the discussion of the timing of tree-ssa,
> > people claimed it was "essential" for 3.5 since there was a tremendous
> > improvement on some C++ cases.  So let's see those cases.
> >
> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747

I've been toying with boost::tie() lately, and the temporary tuple is
still *not* eleminated in the interesting cases, unfortunately.

For an example, look at the code generated for bar(foo&) and baz(foo&)
below, which should be quite similar once the template metaprogram has
been expanded.  However, in the template case, indirection through
references still clutters the generated machine code.

We can do better; bar_neg(foo&) and baz_neg(foo&) show this.  The
template version results in identical code in this case, except that
unnecessary space is allocated on the stack.  (However, this
optimization happens on mainline, too, not just on the branch.)

(Probably this is a different issue, but I had hoped that the tree-ssa
branch would somehow improve things in this area.)

#include <boost/tuple/tuple.hpp>

struct foo {
  int a, b, c, d, e, f, g, h, i, j;
};

template <typename T>
struct make_abs_t
{
  static void doit(const T& t)
  {
    if (t.head < 0) {
      t.head = -t.head;
    }
    make_abs_t<typename T::tail_type>::doit(t.tail);
  }
};

template <typename Car>
struct make_abs_t<boost::tuples::cons<Car, boost::tuples::null_type> >
{
  static void doit(const boost::tuples::cons<Car, boost::tuples::null_type>& t)
  {
    if (t.head < 0) {
      t.head = -t.head;
    }
  }
};

template <typename T>
inline void make_abs(const T& t)
{
  make_abs_t<T>::doit(t);
}

void bar(foo& x)
{
  make_abs(boost::tie(x.a, x.b, x.c, x.d, x.e, x.f, x.g, x.h, x.i, x.j));
}

void baz(foo& x)
{
  if (x.a < 0) x.a = -x.a;
  if (x.b < 0) x.b = -x.b;
  if (x.c < 0) x.c = -x.c;
  if (x.d < 0) x.d = -x.d;
  if (x.e < 0) x.e = -x.e;
  if (x.f < 0) x.f = -x.f;
  if (x.g < 0) x.g = -x.g;
  if (x.h < 0) x.h = -x.h;
  if (x.i < 0) x.i = -x.i;
  if (x.j < 0) x.j = -x.j;
}

template <typename T>
struct make_neg_t
{
  static void doit(const T& t)
  {
    t.head = -t.head;
    make_neg_t<typename T::tail_type>::doit(t.tail);
  }
};

template <typename Car>
struct make_neg_t<boost::tuples::cons<Car, boost::tuples::null_type> >
{
  static void doit(const boost::tuples::cons<Car, boost::tuples::null_type>& t)
  {
    t.head = -t.head;
  }
};

template <typename T>
inline void make_neg(const T& t)
{
  make_neg_t<T>::doit(t);
}

void bar_neg(foo& x)
{
  make_neg(boost::tie(x.a, x.b, x.c, x.d, x.e, x.f, x.g, x.h, x.i, x.j));
}

void baz_neg(foo& x)
{
  x.a = -x.a;
  x.b = -x.b;
  x.c = -x.c;
  x.d = -x.d;
  x.e = -x.e;
  x.f = -x.f;
  x.g = -x.g;
  x.h = -x.h;
  x.i = -x.i;
  x.j = -x.j;
}

Re: [RFC] Contributing tree-ssa to mainline

[Daniel Berlin]

On Jan 17, 2004, at 8:47 AM, Florian Weimer wrote:

> Diego Novillo wrote:
>
>> On Fri, 2004-01-16 at 22:24, Richard Kenner wrote:
>>
>>> Remember that the last time we had the discussion of the timing of 
>>> tree-ssa,
>>> people claimed it was "essential" for 3.5 since there was a 
>>> tremendous
>>> improvement on some C++ cases.  So let's see those cases.
>>>
>> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747
>
> I've been toying with boost::tie() lately, and the temporary tuple is
> still *not* eleminated in the interesting cases, unfortunately.
>
> For an example, look at the code generated for bar(foo&) and baz(foo&)
> below, which should be quite similar once the template metaprogram has
> been expanded.  However, in the template case, indirection through
> references still clutters the generated machine code.
>
> We can do better; bar_neg(foo&) and baz_neg(foo&) show this.  The
> template version results in identical code in this case, except that
> unnecessary space is allocated on the stack.  (However, this
> optimization happens on mainline, too, not just on the branch.)

> (Probably this is a different issue, but I had hoped that the tree-ssa
> branch would somehow improve things in this area.)
>
As Diego stated when SRA was committed, the following limitation exists:
/* Maximum number of fields that a structure should have to be 
scalarized.
    FIXME  This limit has been arbitrarily set to 5.  Experiment to find 
a
     sensible setting.  */
#define MAX_NFIELDS_FOR_SRA 5\x03

This was done, IIRC, to avoid severely increased register pressure.

If you want SRA to do something on your structure, you'll need to 
increase that limit

Re: [RFC] Contributing tree-ssa to mainline

[Florian Weimer]

Daniel Berlin wrote:

> As Diego stated when SRA was committed, the following limitation exists:
> /* Maximum number of fields that a structure should have to be 
> scalarized.
>    FIXME  This limit has been arbitrarily set to 5.  Experiment to find 
> a
>     sensible setting.  */
> #define MAX_NFIELDS_FOR_SRA 5\x03
> 
> This was done, IIRC, to avoid severely increased register pressure.
> 
> If you want SRA to do something on your structure, you'll need to 
> increase that limit

If I go down to two fields/tuples of length two, the optimization
doesn't kick in, either.  8-(

Re: [RFC] Contributing tree-ssa to mainline

[Diego Novillo]

On Sat, 2004-01-17 at 08:47, Florian Weimer wrote:

> (Probably this is a different issue, but I had hoped that the tree-ssa
> branch would somehow improve things in this area.)
> 
Could you open a PR for this test case and assign it to me?


Thanks.  Diego.

Re: [RFC] Contributing tree-ssa to mainline

[Daniel Berlin]

On Jan 17, 2004, at 9:53 AM, Florian Weimer wrote:

> Daniel Berlin wrote:
>
>> As Diego stated when SRA was committed, the following limitation 
>> exists:
>> /* Maximum number of fields that a structure should have to be
>> scalarized.
>>    FIXME  This limit has been arbitrarily set to 5.  Experiment to 
>> find
>> a
>>     sensible setting.  */
>> #define MAX_NFIELDS_FOR_SRA 5\x03
>>
>> This was done, IIRC, to avoid severely increased register pressure.
>>
>> If you want SRA to do something on your structure, you'll need to
>> increase that limit
>
> If I go down to two fields/tuples of length two, the optimization
> doesn't kick in, either.  8-(
Hmmm. Interesting.
Can you file a bug report with this testcase (the length 2, which 
*should* be taken care of already), so it can be tracked?

--Dan

Re: [RFC] Contributing tree-ssa to mainline

[Joseph S. Myers]

On Sat, 17 Jan 2004, Daniel Berlin wrote:

> As Diego stated when SRA was committed, the following limitation exists:
> /* Maximum number of fields that a structure should have to be 
> scalarized.
>     FIXME  This limit has been arbitrarily set to 5.  Experiment to find 
> a
>      sensible setting.  */
> #define MAX_NFIELDS_FOR_SRA 5

Before the merge to mainline, please at least change hardcoded parameters
like this to use --param (which does make experimenting with different
values easier).  I've understood ever since Mark added that option
<http://gcc.gnu.org/ml/gcc-patches/2001-02/msg00800.html> that using it
was the convention, it just hasn't been documented as such.  OK to commit
the following web page patch?  (The beginner.html patch is because it
seems no-one ever took up my suggestion in that thread to add converting
existing parameters to the projects list, and I don't think they've all
been done.  Adding comments to parameters that for whatever reason
shouldn't be converted to --param, saying so, would be useful.)

Index: codingconventions.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/codingconventions.html,v
retrieving revision 1.30
diff -u -r1.30 codingconventions.html
--- codingconventions.html	11 Oct 2003 14:02:53 -0000	1.30
+++ codingconventions.html	17 Jan 2004 17:00:49 -0000
@@ -23,7 +23,8 @@
 
 <ul>
 
-  <li>All command-line options must be documented in the GCC manual.</li>
+  <li>All command-line options (including all <code>--param</code>
+  arguments) must be documented in the GCC manual.</li>
 
   <li>Any change to documented behavior (for example, the behavior of
   a command-line option or a GNU language extension) must include the
@@ -184,6 +185,9 @@
 against <code>error_mark_node</code> rather than by comparing the
 <code>TREE_CODE</code> against <code>ERROR_MARK</code>; see <a
 href="http://gcc.gnu.org/ml/gcc-patches/2000-10/msg00792.html">message</a>.</p>
+
+<p>Internal numeric parameters that may affect generated code should
+be controlled by <code>--param</code> rather than being hardcoded.</p>
 
 
 <h2>Spelling, terminology and markup</h2>
Index: projects/beginner.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/projects/beginner.html,v
retrieving revision 1.43
diff -u -r1.43 beginner.html
--- projects/beginner.html	3 Jan 2004 19:15:42 -0000	1.43
+++ projects/beginner.html	17 Jan 2004 17:00:49 -0000
@@ -414,6 +414,10 @@
 href="../codingconventions.html">GCC coding conventions</a>
 consistently.</li>
 
+<li>Change code to follow the coding conventions in other ways.  For
+example, change arbitrary hardcoded parameters to use the
+<code>--param</code> mechanism.</li>
+
 </ul>
 
 <h2>Port cleanliness</h2>

-- 
Joseph S. Myers
jsm@polyomino.org.uk

Re: [RFC] Contributing tree-ssa to mainline

[Diego Novillo]

On Sat, 2004-01-17 at 12:07, Joseph S. Myers wrote:
> On Sat, 17 Jan 2004, Daniel Berlin wrote:
> 
> > As Diego stated when SRA was committed, the following limitation exists:
> > /* Maximum number of fields that a structure should have to be 
> > scalarized.
> >     FIXME  This limit has been arbitrarily set to 5.  Experiment to find 
> > a
> >      sensible setting.  */
> > #define MAX_NFIELDS_FOR_SRA 5
> 
> Before the merge to mainline, please at least change hardcoded parameters
> like this to use --param (which does make experimenting with different
> values easier).
>
Absolutely.  These are the kinds of basic cleanup activities I had in
mind when I requested peer review and suggested a way of breaking up the
changes.


Thanks.  Diego.

Re: [RFC] Contributing tree-ssa to mainline

[Daniel Berlin]

> Absolutely.  These are the kinds of basic cleanup activities I had in
> mind when I requested peer review and suggested a way of breaking up 
> the
> changes.
>

These are just cleanups that are required before merging to the 
mainline.
I still don't think trying to break up all of tree-ssa and it's 
individual passes and submitting them makes any sense at all.

Unless we are talking about peer review simply for cleanups, and not 
for design issues.
In which case it's a matter of us looking through it ourselves for 
cleanups and whatnot we missed and pointing them out to each other.

I'd seriously rather not go about rehashing the design tradeoffs.

>
> Thanks.  Diego.
>

Re: [RFC] Contributing tree-ssa to mainline

[Mark Mitchell]

On Sat, 2004-01-17 at 09:07, Joseph S. Myers wrote:
> On Sat, 17 Jan 2004, Daniel Berlin wrote:
> 
> > As Diego stated when SRA was committed, the following limitation exists:
> > /* Maximum number of fields that a structure should have to be 
> > scalarized.
> >     FIXME  This limit has been arbitrarily set to 5.  Experiment to find 
> > a
> >      sensible setting.  */
> > #define MAX_NFIELDS_FOR_SRA 5
> 
> Before the merge to mainline, please at least change hardcoded parameters
> like this to use --param (which does make experimenting with different
> values easier).  I've understood ever since Mark added that option
> <http://gcc.gnu.org/ml/gcc-patches/2001-02/msg00800.html> that using it
> was the convention, it just hasn't been documented as such.  OK to commit
> the following web page patch?  (The beginner.html patch is because it
> seems no-one ever took up my suggestion in that thread to add converting
> existing parameters to the projects list, and I don't think they've all
> been done.  Adding comments to parameters that for whatever reason
> shouldn't be converted to --param, saying so, would be useful.)

Yes, these patches to the docs are OK.

-- 
Mark Mitchell <mark@codesourcery.com>
CodeSourcery, LLC

Re: [RFC] Contributing tree-ssa to mainline

[Scott A Crosby]

On Fri, 16 Jan 2004 22:09:35 -0800, Andrew Pinski <pinskia@physics.uc.edu> writes:

> >>> people claimed it was "essential" for 3.5 since there was a
> >>> tremendous
> >>> improvement on some C++ cases.  So let's see those cases.
> >>>
> >> http://gcc.gnu.org/bugzilla/show_bug.cgi?id=12747
> >

There's also PR2399, where bar is a template based representation of a
16x16x16 array:

void bar (D3VolumeIndex<char,D3VolumeFixed<char,16,16,16> >::Index bar) {
  bar[5][4][3]=10;
}

This compiles to a function using 120 bytes of stack space and 25
mov's. It should be a single instruction.

As this would have been in the inner loops for my analysis package, I
switched idioms rather than benchmark the performance degradation. I
expect it would have been hideous, unless inlining and LCM moved the
useless initialization out of the loops.

Scott

Re: [RFC] Contributing tree-ssa to mainline

[Joe Buck]

On Fri, Jan 16, 2004 at 10:24:08PM -0500, Richard Kenner wrote:
>     Expecting tree-ssa to produce code better by a factor of two is simply
>     unreasonable.
> 
> In general, of course.  But if it is really allowing new classes of
> optimizations to be performed (which was the argument to justify the new
> infrastructure), it should be possible to construct test cases that show
> that sort of performance improvement (factors of two or more).

There are certain cases where tree-ssa *already* produces better code by a
factor of two or more.  See, for example PR 12747.

Re: [RFC] Contributing tree-ssa to mainline

[Daniel Berlin]

I'd like to point out that this whole thread is still getting us 
somewhere, and not just filling up inboxes.
Seriously though, I think we've reached the point of diminishing gains. 
We now know how everyone feels.
It appears that this is "most people are in favor, some people are 
against", but everyone seems to have some specific criteria they want 
met before merging.

I'd also like to point out that tree-ssa is, by various benchmarks 
pointed out earlier, in the worst case, slightly slower than the 
mainline in compile time, even though it adds *30* optimization passes.
That's right.
Thirty.
Check tree-optimize if you don't believe me.
That's quite an accomplishment in and of itself if you ask me.

Anyway,  It would be more productive if we were to try to concentrate 
on a specific set of merge criteria for tree-ssa, than continue to 
discuss the benefits or disadvantages of it (since it seems clear the 
overwhelming number of people think it has great benefit already)


You friendly neighborhood cat herder,
Dan

Re: [RFC] Contributing tree-ssa to mainline

[Dale Johannesen]

On Jan 19, 2004, at 3:43 PM, Daniel Berlin wrote:
> I'd like to point out that this whole thread is still getting us 
> somewhere, and not just filling up inboxes.
> Seriously though, I think we've reached the point of diminishing 
> gains. We now know how everyone feels.
> It appears that this is "most people are in favor, some people are 
> against", but everyone seems to have some specific criteria they want 
> met before merging.
> Anyway,  It would be more productive if we were to try to concentrate 
> on a specific set of merge criteria for tree-ssa, than continue to 
> discuss the benefits or disadvantages of it (since it seems clear the 
> overwhelming number of people think it has great benefit already)

IMO the important question to ask is, will tree-ssa be the basis for 
3.5?  If the answer to this is
yes, I believe we should merge immediately even if the current state is 
not what we would like
it to be.  That will reduce everyone's maintenance burden.

> I'd also like to point out that tree-ssa is, by various benchmarks 
> pointed out earlier, in the worst case, slightly slower than the 
> mainline in compile time, even though it adds *30* optimization 
> passes.
> That's right.
> Thirty.
> Check tree-optimize if you don't believe me.
> That's quite an accomplishment in and of itself if you ask me.

It suggests that one pass does not take a lot of time, provided you 
aren't doing much in that pass.
This is in line with my experience (and other people's) on other 
compilers.

Re: [RFC] Contributing tree-ssa to mainline

[Geert Bosch]

On Jan 19, 2004, at 18:43, Daniel Berlin wrote:
> Anyway,  It would be more productive if we were to try to concentrate 
> on a specific set of merge criteria for tree-ssa, than continue to 
> discuss the benefits or disadvantages of it (since it seems clear the 
> overwhelming number of people think it has great benefit already)

The single biggest issue is documentation. As you say, there are thirty
optimization passes. That means that there should be thirty descriptions
of  these passes: specify what the necessary preconditions are before
running the pass (what information needs to be up-to-date etc), what
invariants are maintained, what transformations the pass performs, what
transformations are not done and why (like other pass does xyz), and
what postconditions hold. Also include references to literature where
appropriate, including  deviations from the described algorithms as
well as pitfalls encountered during implementation. Only comments can
describe why certain paths have not been taken.

All data structures need documentation, statements about initialization
and invariants. Every function needs a comment describing its effects
at a sufficiently high level, including precise meaning of all formal
parameters and effects on global data structures.

As explained before, one of the main goals of tree-ssa is to improve
maintainability of the compiler by moving to more standard and easy
to  modify algorithms instead of organically grown intricate webs of
functionality. This argument for change only holds water if the
replacements algorithms are well-documented. In a way it is worse to
have newly written poorly documented code, than similar code that has
been around for ages.

So I would like to push for strict standards for documentation.
All new code must meet the documentation standards *before* merging.
Also, any old code that may be affected by the changes needs to be
reviewed and stale comments need to be updated. In my opinion everything
else is secondary.

   -Geert

Re: [RFC] Contributing tree-ssa to mainline

[Diego Novillo]

On Mon, 2004-01-19 at 22:13, Geert Bosch wrote:
> On Jan 19, 2004, at 18:43, Daniel Berlin wrote:
> > Anyway,  It would be more productive if we were to try to concentrate 
> > on a specific set of merge criteria for tree-ssa, than continue to 
> > discuss the benefits or disadvantages of it (since it seems clear the 
> > overwhelming number of people think it has great benefit already)
> 
> The single biggest issue is documentation.
>
We try to keep it fairly detailed and complete.  The API documentation
is published nightly, created directly from the source code comments. 
As with any evolving piece of code, I will not guarantee that the
documentation is complete, but it should not be hard to derive .texi
documentation out of it.

>  As you say, there are thirty
> optimization passes. That means that there should be thirty descriptions
> of  these passes
>
Fewer, actually.  Some passes are repeated more than once.

> So I would like to push for strict standards for documentation.
> All new code must meet the documentation standards *before* merging.
> Also, any old code that may be affected by the changes needs to be
> reviewed and stale comments need to be updated. In my opinion everything
> else is secondary.
> 
This goes again to my request for peer review.  All the API
documentation is available online.  You don't need to even check-out the
branch.  Follow the links from http://gcc.gnu.org/projects/tree-ssa/
You will find high-level design documents and API documentation.  We
need bugzilla reports that point out specific bits that are missing.  I
have created PR13756 to begin tracking documentation issues.  Feel free
to add what you think is missing.


Thanks.  Diego.

tree-ssa/13756 Documentation issues

[Geert Bosch]

On Jan 19, 2004, at 22:27, Diego Novillo wrote:
> This goes again to my request for peer review.  All the API
> documentation is available online.  You don't need to even check-out 
> the
> branch.  Follow the links from http://gcc.gnu.org/projects/tree-ssa/
> You will find high-level design documents and API documentation.  We
> need bugzilla reports that point out specific bits that are missing.  I
> have created PR13756 to begin tracking documentation issues.  Feel free
> to add what you think is missing.

First comment:

There is no global overview of tree-ssa. The "main page" of the
documentation is empty, and there is no single place that describes
what tree-ssa is and what the overall structure is.

The most useful piece of high-level info is in the proceedings of
the 2003 GCC Summit, page 171-195, but I agree with Richard Kenner that
most of this information should be contained in the various files that
make up tree-ssa.

Unfortunately, the referenced information is in PDF format, so I cannot
easily cut and paste some of it to illustrate my point.

   -Geert