[Bug c/107738] New: Top-level inline-asm is not well documented

["pinskia at gcc dot gnu.org" <gcc-bugzilla@gcc.gnu.org>]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=107738

            Bug ID: 107738
           Summary: Top-level inline-asm is not well documented
           Product: gcc
           Version: 13.0
            Status: UNCONFIRMED
          Keywords: documentation, inline-asm
          Severity: normal
          Priority: P3
         Component: c
          Assignee: unassigned at gcc dot gnu.org
          Reporter: pinskia at gcc dot gnu.org
  Target Milestone: ---

There is only one reference to the top-level inline-asm in the whole user
manual:
https://gcc.gnu.org/onlinedocs/gcc-12.2.0/gcc/Basic-Asm.html#Basic-Asm


There should be a section here talking about common mistakes using top-level
inline-asm including but not limited to:
* assuming the section and alignment where the top-level inline-asm will be
emitted to
** Give examples on how to do push/pop section or using previous_section
*** make a mention this is depdent on the assembler being used
* assuming the order (reference also -fno-toplevel-reorder option) compared to
functions
* Give examples of other types of top-level inline-asm usage
* Make a mention of a limitation dealing with them and LTO and the reason why
you should avoid them and use other ways of doing the same thing instead