target hooks / plugins

[Joern Rennecke]

Quoting "Joseph S. Myers" <joseph@codesourcery.com>:
> If you want to have documentation extracted from source files, you need to
> engage with the SC and FSF at an early stage to get suitable license
> exception wording to permit the relevant text to be used in the manuals as
> well as the main (GPL) sources.

I haven't gotten any reply to my proposal from the 5th of January
http://gcc.gnu.org/ml/gcc/2010-01/msg00082.html

Is the GCC mailing list no longer the right place to reach the  
steering committee?

>  Of course, the ordering and (especially)
> section divisions in the internals manual are human-designed not arbitrary
> so you need to retain the ability to put the documentation of each hook in
> an appropriate position in an appropriate section of the manual.

I have posted my current patch here:
http://gcc.gnu.org/ml/gcc-patches/2010-01/msg00559.html

> If you can make this work it should reduce the risk of people not
> documenting new hooks

We actually have a number of instances where the target hook documentation is
out of sync with the sources.  I have attached a file with my notes on this.

> , but for it to work the FSF agreement is critical

So who do I have to talk to for this?

> as
> is ensuring it genuinely works as well as the existing system without
> regressions (including working in update_web_docs).

tm.texi is half a megabyte, so it would be nice not to have it as a generated
file in the repository.  Also, it'd be annoying to have to regenerate & check
it in for every target.def change even though the build works fine with
the generated file in the build directory.
Will it be acceptable to have update_web_docs build a generator program
(written in C) to rebuild tm.texi?
-------------- next part --------------
various hooks: why are we referring to 'the diagnostic message'?
the context does not suggest a particular one, and I thought we had more
than one in gcc.

various documentation used rtx / tree instead of const_rtx / const_tree.

TARGET_ASM_ASSEMBLE_VISIBILITY: const char *@var{visibility} -> int
clarified current_function_pops_args description and removed comment on
unclear "its arguments" reference.
TARGET_ASM_NAMED_SECTION unsigned int @var{align} -> tree decl
TARGET_ASM_MARK_DECL_PRESERVED tree @var{decl} -> const char *symbol
TARGET_SCHED_ADJUST_COST_2 was undocumented.
TARGET_SCHED_SPECULATE_INSN: Fixed return value description.
TARGET_SCHED_NEEDS_BLOCK_P: int -> bool; rtx @var{insn} -> int dep_status (text is still bogus)
TARGET_SCHED_GEN_CHECK -> TARGET_SCHED_GEN_SPEC_CHECK
TARGET_SCHED_SET_SCHED_FLAGS unsigned int *@var{flags} -> /dev/null
TARGET_VECTORIZE_BUILTIN_VECTORIZED_FUNCTION enum built_in_function @var{code} -> unsigned
TARGET_VECTORIZE_BUILTIN_VECTORIZATION_COST was undocumented.
TARGET_[VECTORIZE_]VECTOR_ALIGNMENT_REACHABLE was undocumented.
TARGET_VECTORIZE_BUILTIN_VEC_PERM was undocumented.
TARGET_VECTORIZE_BUILTIN_VEC_PERM_OK was undocumented.
TARGET_EH_RETURN_FILTER_MODE was undocumented.
TARGET_UNWIND_WORD_MODE was undocumented.
TARGET_BUILTIN_FUNCTION -> TARGET_BUILTIN_DECL
TARGET_RESOLVE_OVERLOADED_BUILTIN addded unsigned int /*location_t*/ loc; tree @var{arglist} -> void *arglist
TARGET_BUILTIN_RECIPROCAL enum tree_code @var{fn} -> unsigned fn
TARGET_CANNOT_COPY_INSN_P was undocumented.
TARGET_EXPAND_BUILTIN_VA_START was undocumented.
TARGET_GIMPLIFY_VA_ARG_EXPR tree *@var{pre_p}, tree *@var{post_p} -> gimple_seq *pre_p, gimple_seq *post_p
TARGET_STDARG_OPTIMIZE_HOOK was undocumented.
TARGET_INTERNAL_ARG_POINTER was undocumented.
TARGET_GET_DRAP_RTX: text was garbled, e.g. confusion macro vs. hook.
TARGET_C_MODE_FOR_SUFFIX was undocumented.
TARGET_VALID_OPTION_ATTRIBUTE_P -> TARGET_OPTION_VALID_ATTRIBUTE_P
TARGET_OPTION_PRINT: new parameters FILE *file, int indent
TARGET_OPTION_PRAGMA_PARSE: (target @var{args}) -> tree, tree
TARGET_EXTRA_LIVE_ON_ENTRY: (bitmap *@var{regs}) -> bitmap
TARGET_HANDLE_PRAGMA_EXTERN_PREFIX was undocumented.
TARGET_HELP bool -> void
TARGET_BUILTIN_SETJMP_FRAME_VALUE bool -> rtx
TARGET_PRETEND_OUTGOING_VARARGS_NAMED: add (CUMULATIVE_ARGS *@var{ca})
TARGET_LEGITIMATE_ADDRESS_P: returns bool
TARGET_SCHED_REORDER2 @var{clock} -> int clock
TARGET_SCHED_DFA_PRE_CYCLE_INSN int -> rtx
TARGET_SCHED_DFA_POST_CYCLE_INSN int -> rtx
TARGET_SCHED_DFA_PRE_CYCLE_ADVANCE -> TARGET_SCHED_DFA_PRE_ADVANCE_CYCLE
TARGET_SCHED_DFA_POST_CYCLE_ADVANCE -> TARGET_SCHED_DFA_POST_ADVANCE_CYCLE
TARGET_SCHED_ALLOC_SCHED_CONTEXT, TARGET_SCHED_INIT_SCHED_CONTEXT, TARGET_SCHED_SET_SCHED_CONTEXT, TARGET_SCHED_CLEAR_SCHED_CONTEXT, TARGET_SCHED_FREE_SCHED_CONTEXT were duplicated.
TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DFA_LOOKAHEAD_GUARD_SPEC int -> bool
TARGET_SCHED_GET_INSN_SPEC_DS was undocumented.
TARGET_SCHED_GET_INSN_CHECKED_DS was undocumented.
TARGET_SCHED_SKIP_RTX_P was undocumented.
TARGET_ASM_RELOC_RW_MASK: 'returns' void.
TARGET_MANGLE_DECL_ASSEMBLER_NAME: void -> tree
TARGET_ASM_EMIT_UNWIND_LABEL was missing types.
Why is the TARGET_DWARF_CALLING_CONVENTION documentation nested in the
DWARF2_DEBUGGING_INFO documentation?
TARGET_MIN_DIVISIONS_FOR_RECIP_MUL int -> unsigned int
TARGET_SHIFT_TRUNCATION_MASK int -> unsigned HOST_WIDE_INT
TARGET_BRANCH_TARGET_REGISTER_CLASS int -> enum reg_class
TARGET_USE_LOCAL_THUNK_ALIAS_P: Not a hook.