From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gcc-bugzilla@gcc.gnu.org>
Received: by sourceware.org (Postfix, from userid 48)
	id D518D3853D7A; Thu, 17 Nov 2022 19:40:42 +0000 (GMT)
DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org D518D3853D7A
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org;
	s=default; t=1668714042;
	bh=/Lujc8fER3i2mKwdy4H/OGUU2pCN1X1n2KYLXRth2VI=;
	h=From:To:Subject:Date:From;
	b=GjhA4hEd9kuC8bcezwxfya2jrKoppkM7N1NSqVAh80082Js4TVq2zZy4fH+YY1vf8
	 bUYBAUmmzznNlY84Hdhu62GyVZYMhWclqCIgUwfzbskwVCMpce3ofkHp5a0aVzAiCu
	 NM80snGFCw6dxWJ/97MPCSFbJbd2otm8QvE+r0Gc=
From: "pinskia at gcc dot gnu.org" <gcc-bugzilla@gcc.gnu.org>
To: gcc-bugs@gcc.gnu.org
Subject: [Bug c/107738] New: Top-level inline-asm is not well documented
Date: Thu, 17 Nov 2022 19:40:42 +0000
X-Bugzilla-Reason: CC
X-Bugzilla-Type: new
X-Bugzilla-Watch-Reason: None
X-Bugzilla-Product: gcc
X-Bugzilla-Component: c
X-Bugzilla-Version: 13.0
X-Bugzilla-Keywords: documentation, inline-asm
X-Bugzilla-Severity: normal
X-Bugzilla-Who: pinskia at gcc dot gnu.org
X-Bugzilla-Status: UNCONFIRMED
X-Bugzilla-Resolution: 
X-Bugzilla-Priority: P3
X-Bugzilla-Assigned-To: unassigned at gcc dot gnu.org
X-Bugzilla-Target-Milestone: ---
X-Bugzilla-Flags: 
X-Bugzilla-Changed-Fields: bug_id short_desc product version bug_status
 keywords bug_severity priority component assigned_to reporter
 target_milestone
Message-ID: <bug-107738-4@http.gcc.gnu.org/bugzilla/>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
X-Bugzilla-URL: http://gcc.gnu.org/bugzilla/
Auto-Submitted: auto-generated
MIME-Version: 1.0
List-Id: <gcc-bugs.sourceware.org>

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

            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 w=
hy
you should avoid them and use other ways of doing the same thing instead=