How to document many darwin-specific, undocumented target macros

[Steven Bosscher <stevenb dot gcc at gmail dot com>]

Hello,

By my count, there are a lot of undocumented target macro defines that
are darwin specific. In total there are 59 undocumented cases, and 16
of them are darwin specific.
(To get to this count, I've simply looked at all #defines in config/*
+ config/*/*, looked up the ones that are used in the gcc/ directory,
and that are not documented in doc/*.texi -- see full list at the
bottom of this e-mail).

The darwin specific cases are the following:
COLLECT_RUN_DSYMUTIL
DEBUG_ABBREV_SECTION
DEBUG_ARANGES_SECTION
DEBUG_FRAME_SECTION
DEBUG_INFO_SECTION
DEBUG_LINE_SECTION
DEBUG_LOC_SECTION
DEBUG_MACINFO_SECTION
DEBUG_MACRO_SECTION
DEBUG_PUBNAMES_SECTION
DEBUG_PUBTYPES_SECTION
DEBUG_RANGES_SECTION
DEBUG_STR_SECTION
DSYMUTIL
FRAME_BEGIN_LABEL
ASM_DEBUG_SPEC

Most of them deal with debugging things that Mach-O does not support
in the "normal" way that ELF does, e.g. all the DEBUG_*_SECTION
defines, like so:

dwarf2out.c:#define DEBUG_FRAME_SECTION ".debug_frame"
config/darwin.h:#define DEBUG_FRAME_SECTION
"__DWARF,__debug_frame,regular,debug"
dwarf2out.c:#define DEBUG_INFO_SECTION  ".debug_info"
config/darwin.h:#define DEBUG_INFO_SECTION
"__DWARF,__debug_info,regular,debug"
dwarf2out.c:#define DEBUG_ABBREV_SECTION        ".debug_abbrev"
config/darwin.h:#define DEBUG_ABBREV_SECTION
"__DWARF,__debug_abbrev,regular,debug"
dwarf2out.c:#define DEBUG_ARANGES_SECTION       ".debug_aranges"
config/darwin.h:#define DEBUG_ARANGES_SECTION
"__DWARF,__debug_aranges,regular,debug"
dwarf2out.c:#define DEBUG_MACINFO_SECTION       ".debug_macinfo"
config/darwin.h:#define DEBUG_MACINFO_SECTION
"__DWARF,__debug_macinfo,regular,debug"
dwarf2out.c:#define DEBUG_LINE_SECTION  ".debug_line"
config/darwin.h:#define DEBUG_LINE_SECTION
"__DWARF,__debug_line,regular,debug"
dwarf2out.c:#define DEBUG_LOC_SECTION   ".debug_loc"
config/darwin.h:#define DEBUG_LOC_SECTION
"__DWARF,__debug_loc,regular,debug"
dwarf2out.c:#define DEBUG_PUBNAMES_SECTION      ".debug_pubnames"
config/darwin.h:#define DEBUG_PUBNAMES_SECTION
"__DWARF,__debug_pubnames,regular,debug"
dwarf2out.c:#define DEBUG_PUBTYPES_SECTION      ".debug_pubtypes"
config/darwin.h:#define DEBUG_PUBTYPES_SECTION
"__DWARF,__debug_pubtypes,regular,debug"
dwarf2out.c:#define DEBUG_STR_SECTION   ".debug_str"
config/darwin.h:#define DEBUG_STR_SECTION
"__DWARF,__debug_str,regular,debug"
dwarf2out.c:#define DEBUG_RANGES_SECTION        ".debug_ranges"
config/darwin.h:#define DEBUG_RANGES_SECTION
"__DWARF,__debug_ranges,regular,debug"


I am not sure how to proceed with these target macros. I could
documenting these target macros, but where are the default names taken
from (a spec somewhere), and is this the Right solution given that
only darwin uses non-default names? In fact darwin does follow the
naming convention, the only difference is that it wraps the section
name in a segment label (always "__DWARF__") and adds some flags
(always "regular,debug"). I would have expected there to be a way to
change a section name in a target-specific way (something like a
targetm.asm_out.adjust_section_name to transform ".debug_blah" to
"__DWARF,__debug_blah,regular,debug") but it seems such a mechanism
doesn't exist. Maybe add a hook for this?

Thoughts/comments/suggestions welcome...

Ciao!
Steven






Complete list:
missing: ADDR_VEC_ALIGN
missing: ADJUST_INSN_LENGTH
missing: ASCII_DATA_ASM_OP
missing: ASM_OUTPUT_ADDR_DIFF_VEC
missing: ASM_OUTPUT_ADDR_VEC
missing: ASM_OUTPUT_EXTERNAL_LIBCALL
missing: ASM_OUTPUT_LIMITED_STRING
missing: ASM_PN_FORMAT
missing: COLLECT_RUN_DSYMUTIL
missing: CPU_UNITS_QUERY
missing: DEBUG_ABBREV_SECTION
missing: DEBUG_ARANGES_SECTION
missing: DEBUG_FRAME_SECTION
missing: DEBUG_INFO_SECTION
missing: DEBUG_LINE_SECTION
missing: DEBUG_LOC_SECTION
missing: DEBUG_MACINFO_SECTION
missing: DEBUG_MACRO_SECTION
missing: DEBUG_PUBNAMES_SECTION
missing: DEBUG_PUBTYPES_SECTION
missing: DEBUG_RANGES_SECTION
missing: DEBUG_STR_SECTION
missing: DSYMUTIL
missing: DWARF2_ADDR_SIZE
missing: ELF_ASCII_ESCAPES
missing: ELF_STRING_LIMIT
missing: FENCE_FOLLOWING_MOVNT
missing: FP_REG_P
missing: FRAME_BEGIN_LABEL
missing: HAVE_AS_LEB128
missing: HAVE_AS_TLS
missing: INSN_LENGTH_ALIGNMENT
missing: IS_STACK_MODE
missing: JCR_SECTION_NAME
missing: JMP_BUF_SIZE
missing: LOGICAL_OP_NON_SHORT_CIRCUIT
missing: MY_ISCOFF
missing: NAME__MAIN
missing: NORMAL_MODE
missing: PIC_CASE_VECTOR_ADDRESS
missing: READ_CAN_USE_WRITE_PREFETCH
missing: SPARC_STACK_BOUNDARY_HACK
missing: STACK_POP_CODE
missing: STACK_REG_P
missing: STRING_ASM_OP
missing: SYMBOL__MAIN
missing: TARGET_64BIT
missing: TARGET_64BIT_DEFAULT
missing: TARGET_AIX_VERSION
missing: TARGET_SCHED_FIRST_CYCLE_MULTIPASS_DATA_T
missing: VMS_DEBUG_MAIN_POINTER
missing: ASM_DEBUG_SPEC
missing: EXTRA_SPEC_FUNCTIONS
missing: GOMP_SELF_SPECS
missing: GTM_SELF_SPECS
missing: LINK_SSP_SPEC
missing: MFLIB_SPEC
missing: MFWRAP_SPEC
missing: STARTFILE_PREFIX_SPEC