After thinking about this some more, I believe I have some better text.
Previously I used the word "discouraged" to describe this practice. The
existing docs use the term "avoid." I believe what you want is
something more like the attached. Direct and clear, just like docs
should be.
If you are ok with this, I'll send it to gcc-patches.
dw
+While it
+is discouraged, it is possible to write your own prologue/epilogue
code
+using asm and use ``C'' code in the middle.
I wouldn't remove the last sentence since IMO it's not the intent of
the feature
to ever support that and the compiler doesn't guarantee it and may
result
in wrong code given that `naked' is a fragile low-level feature.
I'm assuming you meant "would remove."
I wasn't comfortable including that sentence, but I was following the
existing docs. Since they said you could "only" use basic asm,
following that with a warning to "avoid" locals/if/etc was really
confusing without this text.
Also, as ugly as this is, apparently some people really do this
(comment 6): https://gcc.gnu.org/bugzilla/show_bug.cgi?id=43404#c6
We don't have to doc every crazy thing people try to do with gcc. But
since it's out there, maybe we should this time? If only to
discourage it.
I'm *slightly* more in favor of keeping it. But if you still feel it
should go, it's gone.
Index: extend.texi
===================================================================
--- extend.texi (revision 210624)
+++ extend.texi (working copy)
@@ -3332,16 +3332,15 @@
@item naked
@cindex function without a prologue/epilogue code
-Use this attribute on the ARM, AVR, MCORE, MSP430, NDS32, RL78, RX and SPU
-ports to indicate that the specified function does not need prologue/epilogue
-sequences generated by the compiler.
-It is up to the programmer to provide these sequences. The
-only statements that can be safely included in naked functions are
-@code{asm} statements that do not have operands. All other statements,
-including declarations of local variables, @code{if} statements, and so
-forth, should be avoided. Naked functions should be used to implement the
-body of an assembly function, while allowing the compiler to construct
-the requisite function declaration for the assembler.
+This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32,
+RL78, RX and SPU ports. It allows the compiler to construct the
+requisite function declaration, while allowing the body of the
+function to be assembly code. The specified function will not have
+prologue/epilogue sequences generated by the compiler. Only Basic
+@code{asm} statements can safely be included in naked functions
+(@pxref{Basic Asm}). While using Extended @code{asm} or a mixture of
+Basic @code{asm} and ``C'' code may appear to work, they cannot be
+depended upon to work reliably and are not supported.
@item near
@cindex functions that do not handle memory bank switching on 68HC11/68HC12
@@ -6269,6 +6268,8 @@
efficient code, and in most cases it is a better solution. When writing
inline assembly language outside of C functions, however, you must use Basic
@code{asm}. Extended @code{asm} statements have to be inside a C function.
+Functions declared with the @code{naked} attribute also require Basic
+@code{asm} (@pxref{Function Attributes}).
Under certain circumstances, GCC may duplicate (or remove duplicates of) your
assembly code when optimizing. This can lead to unexpected duplicate
@@ -6388,6 +6389,8 @@
Note that Extended @code{asm} statements must be inside a function. Only
Basic @code{asm} may be outside functions (@pxref{Basic Asm}).
+Functions declared with the @code{naked} attribute also require Basic
+@code{asm} (@pxref{Function Attributes}).
While the uses of @code{asm} are many and varied, it may help to think of an
@code{asm} statement as a series of low-level instructions that convert input
