On 9/20/2016 12:36 PM, Gerald Pfeifer wrote:
[ Old e-mail alert ]
On Sat, 19 Dec 2015, David Wohlferd wrote:
I have been discussing adding some content to the basic asm docs. As part of
this work, I want to add a discussion of "How to convert basic asm to extended
asm." However it doesn't seem like this is a good fit for the User Guide.
This is both because the UG doesn't generally talk about "How To" write code,
and because the text may need updates more often than the UG gets released.
For the latter, could referring to gcc.gnu.org/onlinedocs (in particular
the trunk version there) be a viable option?
That gets updated daily, so not a question of waiting for the next
release.
1) Is it appropriate for the UG to link to sections in the wiki? I
see that we do, but should we?
Generally, I think that is fine. It does require Internet access
and you run into the opposite of what you describe above (the Wiki
might have moved to coverage of a later version of GCC), but then
so does what I described at the beginning of this message.
Generally, I also think that we should not spread things across too
many places, and our documentation should be mostly self contained.
(The particular use case you had in mind, seems fine for the Wiki
or the web pages -- and I'm thinking of our porting_to.html pages
that we have had for the last couple of major releases.)
In the time since my email was sent, there has been good news and bad
news on this subject:
The good news is that the wiki content got created (see
https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended) and a reference has
been added to the docs (see
https://gcc.gnu.org/onlinedocs/gcc/Basic-Asm.html).
The bad news is that the original intent of this doc was that it would
be included as part of completely deprecating using Basic Asm in
functions (BAIF), or at least adding a warning to help people find and
convert at-risk code. However when I sent the patches to do these
things, I was unable to convince anyone to sign off on either of them.<sigh>
Moving on, I am contemplating creating some additional content on a
related subject, so perhaps you would care to voice your opinion as to
the value and best location for this content.
The gcc docs are able to "get away" with not documenting a great deal of
behavior for the compiler. This is because the compiler is merely
implementing the C/C++ standards. If someone wants to know how a
particular feature is intended to work, they can read the standard and
assume that's what the compiler does.
However this approach doesn't apply when gcc adds extensions to the
standard. In these cases, the gcc docs must provide 100% of the
information for using the feature. Anything not listed as explicitly
supported is (by definition) "undefined" behavior. Having a program's
function depend upon undefined behavior is risky, and is usually
described as "a bad thing."
I believe the decision to continue to support BAIF necessitates
documenting (somewhere) this gcc extension to clearly specify which uses
are supported and which are not. As a first cut, I intend to define a
list of common programming tasks and document which ones are and are not
supported. Obviously this list can never be complete, but by explicitly
listing some of the more common tasks, we can at least begin to steer
people away from known-bad ideas. Off the top of my head:
- read/write global variables
- read/write function parameters
- read/write local variables
- return value from function
- modify registers (without restoring)
- modify flags (without restoring)
- modify the stack (push/pop/mov to/mov from)
- call a function
- invoke top-level asm
- jump outside single asm
- throw exceptions
- accessing variables declared in asm
That's probably enough for a start.
Unfortunately, anything we don't list remains "undefined behavior."
Icky, I know, but right now EVERYTHING is undefined. We are leaving
people to guess about what might be safe, and hope that "It's worked
that way for a long time" or "Lots of people do it" implies that it will
always work that way. Talk about icky...
I intend to categorize each of these as one of:
A) Unsupported - While this might appear to work, that is merely
happenstance and cannot be depended upon. Even if there are no
circumstances today where this will fail, this behavior is not supported
and may fail in future releases.
B) Partial - This operation is safe under specific conditions.
C) Supported - This operation is safe and will not be mangled by
optimizations.
At first read, I see 1(?) for category C, 3 for category B, and the rest
are A. However, as "the guy who wants to kill BAIF," perhaps I'm being
too harsh.
Indeed, the biggest challenge for this project will be finding someone
who is prepared to sign off on the accuracy of this kind of doc. Coming
up with examples to show why things belong in A is probably easier than
finding someone who is prepared to approve a statement that one of these
is "safe."
Still, I remain hopeful that if I create the content, someone will step
up to review it.
If anyone has any thoughts about how to approach this, where the
finished content belongs, or wants to volunteer to help, you know where
to find me. Alternately, if someone is going to shoot down this whole
idea, this is the best time for that too...
dw
