(checkdescriptor::create ("check_debug_abbrev")
.groups ("@low")
.prereq <typeof (*_m_sec_abbr)> ()
- .prereq <typeof (*_m_cu_headers)> ());
+ .prereq <typeof (*_m_cu_headers)> ()
+ .description (
+"Checks for low-level structure of .debug_abbrev. In addition it\n"
+"checks:\n"
+" - that all abbreviation tables are non-empty\n"
+" - that certain attribute forms match expectations (mainly those that\n"
+" we have to work with in subsequent check passes. For example we\n"
+" check that DW_AT_low_pc has a form of DW_FORM_{,ref_}addr)\n"
+" - that all CUs that share an abbrev table are of the same DWARF\n"
+" version\n"
+" - that each abbrev table is used\n"
+" - that abbrevs don't share abbrev codes\n"
+" - that abbrev tags, attribute names and attribute forms are all known\n"
+" (note that this assumes that elfutils know about all tags used in\n"
+" practice. Be sure to build against recent-enough version)\n"
+" - that the value of has_children is either 0 or 1\n"
+" - that DW_AT_sibling isn't formed as DW_FORM_ref_addr, and that it\n"
+" isn't present at childless abbrevs\n"
+" - that attributes are not duplicated at abbrev\n"
+" - that DW_AT_high_pc is never used without DW_AT_low_pc. If both are\n"
+" used, that DW_AT_ranges isn't also used\n"
+"This check generally requires CU headers to be readable, i.e. that the\n"
+".debug_info section is roughly well-defined. If that isn't the case,\n"
+"many checks will still be done, operating under assumption that what\n"
+"we see is the latest DWARF format. This may render some checks\n"
+"inaccurate.\n"));
return cd;
}