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: RFC: Doc update for attribute


On 05/20/2014 03:02 AM, David Wohlferd wrote:
> 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.

David, Thanks for the new patch.

> If you are ok with this, I'll send it to gcc-patches.

Looks good to me.

Cheers,
Carlos.

> 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 


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