$target.h vs $target-protos.h

$target.h vs $target-protos.h

[Sandra Loosemore]

The internals manual says that a backend for $target should have 
$target.h and $target-protos.h files, but doesn't say what the 
difference between them is or what belongs in which file.  Current 
practice seems to be a mix of

(1) $target.h contains macro definitions and $target-protos.h contains 
extern declarations.

(2) $target.h defines the external interface to the backend (the macros 
documented in the internals manual) and $target-protos.h contains things 
shared between $target.c and the various .md files.

But some generic source files include $target.h only and some source 
files include both, which wouldn't be true if either of the above models 
applied.  So is there some other logical way to explain the difference 
and what goes where?

The thing that got me thinking about this is looking at a new port 
originally written by a customer, where it seems like there is too much 
stuff in $target.h.  Then I started chasing it down....

- FUNCTION_BOUNDARY depends on which arch variant is being compiled for

- Its expansion references some internal target data structures and 
enumerators to look up that info

- The default definition of TARGET_PTRMEMFUNC_VBIT_LOCATION uses 
FUNCTION_BOUNDARY

- ipa-prop.c uses TARGET_PTRMEMFUNC_VBIT_LOCATION but doesn't include 
$target-protos.h

- tree.c also uses FUNCTION_BOUNDARY directly without including 
$target-protos.h

- Probably there are many other target macros that potentially have 
similar issues

- Presumably this means everything referenced in the expansion of any 
target macro in $target.h also needs to be declared in $target.h and not 
depend on $target-protos.h also being included at the point of use.

So what is the purpose of having a separate $target-protos.h?

-Sandra the confused

Re: $target.h vs $target-protos.h

[Joseph Myers]

On Sun, 18 Feb 2018, Sandra Loosemore wrote:

> So what is the purpose of having a separate $target-protos.h?

It looks like the original explanation was 
<https://gcc.gnu.org/ml/gcc-patches/1999-09n/msg00866.html>, "Because 
tm_p.h needs to be included after tree.h and rtl.h.".

It's certainly still true that rtl.h requires tm.h to have been included 
first.  It's also true that tm_p.h depends on types beyond those for which 
simple forward declarations suffice - for example, the machine_mode enum 
(and now the various classes related to machine modes).  So maybe in 1999 
there would have been circular dependencies on types from tree.h and 
rtl.h.

Now more things are included in coretypes.h (including e.g. the 
machine_mode enum via insn-modes.h).  I don't know if circular dependency 
issues would still arise; any global move of prototypes into tm.h would 
require building cc1 for all architectures to locate any such problems.  
(Presumably the prototypes would also all need to be disabled for 
USED_FOR_TARGET.)

An alternative to adding more tm_p.h includes or moving prototypes into 
tm.h would be, if there are only a few target macros involved, converting 
those target macros into hooks.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: $target.h vs $target-protos.h

[Sandra Loosemore]

On 02/18/2018 12:10 PM, Joseph Myers wrote:
> On Sun, 18 Feb 2018, Sandra Loosemore wrote:
> 
>> So what is the purpose of having a separate $target-protos.h?
> 
> It looks like the original explanation was
> <https://gcc.gnu.org/ml/gcc-patches/1999-09n/msg00866.html>, "Because
> tm_p.h needs to be included after tree.h and rtl.h.".
> 
> It's certainly still true that rtl.h requires tm.h to have been included
> first.  It's also true that tm_p.h depends on types beyond those for which
> simple forward declarations suffice - for example, the machine_mode enum
> (and now the various classes related to machine modes).  So maybe in 1999
> there would have been circular dependencies on types from tree.h and
> rtl.h.

Thanks, this makes sense.  I think I could produce a documentation patch 
that explains that the difference is early vs late inclusion, and 
explains that any declarations involving tree or rtx types must go in 
$target-protos.h because those types are not defined when $target.h is 
included.

> Now more things are included in coretypes.h (including e.g. the
> machine_mode enum via insn-modes.h).  I don't know if circular dependency
> issues would still arise; any global move of prototypes into tm.h would
> require building cc1 for all architectures to locate any such problems.
> (Presumably the prototypes would also all need to be disabled for
> USED_FOR_TARGET.)

I don't really want to go there, but maybe target maintainers might want 
to do that when Stage 1 re-opens.

> An alternative to adding more tm_p.h includes or moving prototypes into
> tm.h would be, if there are only a few target macros involved, converting
> those target macros into hooks.

Yup, although again this is Stage 1 material.

So am I right in thinking it is actually not possible to have a .h file 
for internal bits shared between $target.c and the .md files, without 
hacking e.g. genrecog.c which currently emits a fixed set of include 
directives?

-Sandra

Re: $target.h vs $target-protos.h

[Joseph Myers]

On Sun, 18 Feb 2018, Sandra Loosemore wrote:

> Thanks, this makes sense.  I think I could produce a documentation patch that
> explains that the difference is early vs late inclusion, and explains that any
> declarations involving tree or rtx types must go in $target-protos.h because
> those types are not defined when $target.h is included.

That's not the case now for tree or rtx types, since they're (forward) 
declared in coretypes.h.  It may still be the case for some types, but not 
those.

> So am I right in thinking it is actually not possible to have a .h file for
> internal bits shared between $target.c and the .md files, without hacking e.g.
> genrecog.c which currently emits a fixed set of include directives?

I'm not aware of a way to do that.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: $target.h vs $target-protos.h

[Sandra Loosemore]

On 02/19/2018 09:45 AM, Joseph Myers wrote:
> On Sun, 18 Feb 2018, Sandra Loosemore wrote:
> 
>> Thanks, this makes sense.  I think I could produce a documentation patch that
>> explains that the difference is early vs late inclusion, and explains that any
>> declarations involving tree or rtx types must go in $target-protos.h because
>> those types are not defined when $target.h is included.
> 
> That's not the case now for tree or rtx types, since they're (forward)
> declared in coretypes.h.  It may still be the case for some types, but not
> those.

OK, I think I misunderstood your previous message -- it's the 
machine_mode-related types that have the circular dependency, but rtx 
and tree no longer do.  Is that right?

> 
>> So am I right in thinking it is actually not possible to have a .h file for
>> internal bits shared between $target.c and the .md files, without hacking e.g.
>> genrecog.c which currently emits a fixed set of include directives?
> 
> I'm not aware of a way to do that.

Thinking about it some more, perhaps in $target-protos.h

#ifdef IN_TARGET_CODE
#include "$target-internal.h"
#endif

??

-Sandra

Re: $target.h vs $target-protos.h

[Joseph Myers]

On Mon, 19 Feb 2018, Sandra Loosemore wrote:

> On 02/19/2018 09:45 AM, Joseph Myers wrote:
> > On Sun, 18 Feb 2018, Sandra Loosemore wrote:
> > 
> > > Thanks, this makes sense.  I think I could produce a documentation patch
> > > that
> > > explains that the difference is early vs late inclusion, and explains that
> > > any
> > > declarations involving tree or rtx types must go in $target-protos.h
> > > because
> > > those types are not defined when $target.h is included.
> > 
> > That's not the case now for tree or rtx types, since they're (forward)
> > declared in coretypes.h.  It may still be the case for some types, but not
> > those.
> 
> OK, I think I misunderstood your previous message -- it's the
> machine_mode-related types that have the circular dependency, but rtx and tree
> no longer do.  Is that right?

The machine_mode-related types don't either (since coretypes.h includes 
insn-modes.h and machmode.h).  Some types may well still have that 
dependency, but I don't know which.

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: $target.h vs $target-protos.h

[Richard Sandiford]

Joseph Myers <joseph@codesourcery.com> writes:
> On Mon, 19 Feb 2018, Sandra Loosemore wrote:
>
>> On 02/19/2018 09:45 AM, Joseph Myers wrote:
>> > On Sun, 18 Feb 2018, Sandra Loosemore wrote:
>> > 
>> > > Thanks, this makes sense.  I think I could produce a documentation patch
>> > > that
>> > > explains that the difference is early vs late inclusion, and explains that
>> > > any
>> > > declarations involving tree or rtx types must go in $target-protos.h
>> > > because
>> > > those types are not defined when $target.h is included.
>> > 
>> > That's not the case now for tree or rtx types, since they're (forward)
>> > declared in coretypes.h.  It may still be the case for some types, but not
>> > those.
>> 
>> OK, I think I misunderstood your previous message -- it's the
>> machine_mode-related types that have the circular dependency, but rtx and tree
>> no longer do.  Is that right?
>
> The machine_mode-related types don't either (since coretypes.h includes 
> insn-modes.h and machmode.h).  Some types may well still have that 
> dependency, but I don't know which.

The main one I remember is rtx_code, but that can only be used in
$target-protos.h when RTX_CODE is defined.

Richard

Re: $target.h vs $target-protos.h

[Georg-Johann Lay]

Sandra Loosemore schrieb:
> The internals manual says that a backend for $target should have 
> $target.h and $target-protos.h files, but doesn't say what the 
> difference between them is or what belongs in which file.  Current 
> practice seems to be a mix of
> 
> (1) $target.h contains macro definitions and $target-protos.h contains 
> extern declarations.
> 
> (2) $target.h defines the external interface to the backend (the macros 
> documented in the internals manual) and $target-protos.h contains things 
> shared between $target.c and the various .md files.
> 
> But some generic source files include $target.h only and some source 
> files include both, which wouldn't be true if either of the above models 
> applied.  So is there some other logical way to explain the difference 
> and what goes where?

IIRC, one difference is scanning for GTY markers used to tag ggc roots: 
$target.h is scanned whereas $target-protos.h is not (and AFAIR adding 
$target-protos.h in config.gcc to the files being scanned pops up other 
problems). Hence when you have a target-specific GTYed structure that's 
shared by several back-end modules, you'd add the struct definition to 
$target.h (If only one module needs such objects, then you'd add the 
type definition to, say, $target.c which is scanned — or can be rendered 
to a scanned one by adjusting config.gcc).

The bulk of code is not GTYed, of course, and from my experience the 
usage of the mentioned files is like you summarized: $target-protos.h is 
usually a blob of prototypes used internally to communicate within a 
back-end, whereas $target.h "defines" the backend part that's not yet 
hookized, e.g. the TARGET_ macros that define (initializers for) 
register classes etc.

And the usage in libgcc might be different: $target.h is used in libgcc 
(which is the reason for why $target.h might need runtime library 
exceptions, cf. PR61152: 
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=61152#c0 ) Ideally, all 
information needed by libgcc and other target libraries would be shipped 
by built-in macros, but such complete separation from compiler sources 
from libgcc sources is not yet complete to the best of my knowledge. 
$target-protos.h (via tm_p.h), however, is not used by libgcc.

Johann

> The thing that got me thinking about this is looking at a new port 
> originally written by a customer, where it seems like there is too much 
> stuff in $target.h.  Then I started chasing it down....
> 
> - FUNCTION_BOUNDARY depends on which arch variant is being compiled for
> 
> - Its expansion references some internal target data structures and 
> enumerators to look up that info
> 
> - The default definition of TARGET_PTRMEMFUNC_VBIT_LOCATION uses 
> FUNCTION_BOUNDARY
> 
> - ipa-prop.c uses TARGET_PTRMEMFUNC_VBIT_LOCATION but doesn't include 
> $target-protos.h
> 
> - tree.c also uses FUNCTION_BOUNDARY directly without including 
> $target-protos.h
> 
> - Probably there are many other target macros that potentially have 
> similar issues
> 
> - Presumably this means everything referenced in the expansion of any 
> target macro in $target.h also needs to be declared in $target.h and not 
> depend on $target-protos.h also being included at the point of use.
> 
> So what is the purpose of having a separate $target-protos.h?
> 
> -Sandra the confused