Re: __builtin_extend_pointer

[Jim Wilson <wilson at specifixinc dot com>]

On Wed, 2004-06-16 at 13:40, Benjamin Kosnik wrote:
> Yes. I guess I'm having problems telling the difference between builtins
> that are supposed to be used, and builtins that are not supposed to be
> used.

My quickie rule of thumb is that if it is implemented in except.c, then
it is an internal EH built-in, not a user one.  All of the ones I
mentioned are implemented in except.c.

> I'm having problems finding any documentation at all (extend.texi,
> builtins.def, builtins.c) so perhaps you can direct me to what, exactly,
> you mean by "put some docs in the comments."

It is entirely possible that my comments are inadequate.  It is hard for
me to see anything wrong here though, as the comments make perfect sense
to me, but then they should, considering that I wrote the code.  What I
need is someone else to tell me what was left out.

There is a two line comment in libstdc++/libsupc++/eh_personality.cc
  /* For targets with pointers smaller than the word size, we must
extend the
     pointer, and this extension is target dependent.  */
There is a two line comment in gcc/except.c
/* Convert a ptr_mode address ADDR_TREE to a Pmode address controlled by
   POINTERS_EXTEND_UNSIGNED and return it.  */

The two comments say essentially the same thing in different ways, and
seems a sufficient explanation to me for the code, though it does
require some understanding of the difference between ptr_mode and Pmode.

I see the comments don't say anything about why we need to extend the
pointer.  Maybe that is the problem?

> However, my preference is to document all builtins, and note the ones
> that are intended to be used by the general public explicitly.

I agree, that is why I was careful to talk about "user documentation". 
We currently have two gcc documents, one for users, and one for
internals.  Currently, the only documentation section for builtin
functions is in the user doc.  I think that what we need is a section in
the internal doc for internal built in functions.  I don't know where to
put this, or how to word it, or how to structure it, etc.  If someone
else can figure out how to solve this, then I am willing to put
__builtin_extend_pointer docs there.

I don't believe we should put any documentation for the internal
built-in functions in the user doc.
-- 
Jim Wilson, GNU Tools Support, http://www.SpecifixInc.com