This is the mail archive of the gcc@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: doc maintainer questions


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]