This is the mail archive of the gcc-patches@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: [patch, doc] copy-edit inline asm sections



On 2/5/2015 9:13 AM, Sandra Loosemore wrote:
In addition to fixing markup and capitalization, I've moved things around a little bit to improve the flow, and rephrased a few things that I thought were awkward or confusing. I propose to commit this in a few days unless somebody tells me meanwhile that I've broken something.... there's no doubt a lot more that could be done to improve this section further, but I hope this is at least an incremental improvement.

Looks like some good changes here.  I do have a few suggestions:

Patch line 34: You wrote "within a function, but if you want to include assembly language at". How about "within a function, but to include assembly language at" instead?

Patch line 157: You changed "AssemblerInstructions" to "assembler instructions". How about "@var{AssemblerInstructions}" instead?

Patch line 653: You wrote "Use the @samp{&} constraint modifier (@pxref{Modifiers}) on output" how about "Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output" instead?

Under Input parameters, the existing text says "Specify input operands by using the format:". Shouldn't this match the change you made to Output parameters (Patch line 557) "Operands are separated by commas. Each operand has this format:".

Patch line 780: You wrote "Specifies a symbolic name for the operand.o". How about "Specifies a symbolic name for the operand." instead?

Patch line 788: You lost something important when you used copy/paste for the information describing the (zero-based) position from output to input. The old text for input said "if there are two output parameters and three inputs, @code{%2} refers to the first input, @code{%3} to the second, and @code{%4} to the third." You changed this to just "For example if there are three output operands, use @samp{%0} in the template to refer to the first, @samp{%1} for the second, and @samp{%2} for the third." which makes sense for output, but not when you copy it down to input.

Patch line 905: You changed "/* No outputs. */" to "/* No outputs. /*", but I think the original text was correct.

I understand your (apparent) desire to remove duplicated information. However, sometimes I think duplicating information serves a purpose. The asm docs are really long, and having certain information only appear in one place, no matter how logical that place is, might not be sufficient to make the information available at the point where the user needs it. For that reason, I ask you to reconsider removing the duplication for the max # of parameters, and the fact that having no output parameters results in the statement being implicitly volatile. If you absolutely can't stand it, then go ahead and remove them.

====================
Since this last set of changes got checked in, I have been hanging out at stackoverflow to see how people are using inline asm and what types of questions they have. I have collected a few additional changes:

1) (Basic asm) Describe what "top level" asm is and how it works. Combining my changes with yours gives:

Using extended @code{asm} will typically produce smaller, safer, and more
efficient code, and in most cases it is a better solution than basic
@code{asm}.  However, unlike extended @code{asm} which can only be used
in functions, basic @code{asm} can be included at file scope (sometimes
referred to as "Top Level asm").  This technique is sometimes used to
define assembly routines or assembly language macros that can be invoked
elsewhere.  Unlike standard C global initializers (which also appear at
file scope), Top Level asm is not automatically executed at startup or
shutdown.  To execute code defined at file scope, it must explicitly be
called from some other location in your code.

Functions declared with the @code{naked} attribute also require basic
@code{asm} (@pxref{Function Attributes}).

2) (Extended asm) Copy the "may not perform jumps" text from GotoLabels to AssemblerTemplate.

While you seem to have an aversion to duplicating text, I was seriously considering copying this text into the AssemblerTemplate section. While describing it in the context of "goto" made sense at the time, if you aren't writing a "asm goto" statement, you might never see this warning:

@code{asm} statements may not perform jumps into other @code{asm} statements.
GCC's optimizers do not know about these jumps; therefore they cannot take
account of them when deciding how to optimize.

3) (Extended asm) Describe the (relatively new) support for escaping dialect chars (r198641).

Sometime after I wrote the text saying "Also, there is no ``escape'' for an open brace (@{), so do not use open braces in an Extended @code{asm} template other than as a dialect indicator.", someone added support for it. In addition to removing that text, this should get added next to %= and %%:

@item
"%@{" outputs a "@{" into the assembler code.
@item
"%|" outputs a "|" into the assembler code.
@item
"%@}" outputs a "@}" into the assembler code.
@item

4) (Extended asm) A change to Output parameters re the 30 parameter maximum:

Output operands marked as @samp{+} (input + output) count as 2 operands.

5) (Extended asm) Describe %l[label] feature for asm goto.

Alternately, you can reference labels using the actual label name enclosed
in brackets.  For example, to reference a label named @code{carry}, you can
use @code{%l[carry]}.  The label must still be listed in the GotoLabels
section when using this alternate approach.

6) (Symbol-Renaming Pragmas) Put back the text as Rainer Orth requested:

-assembly for a given declaration. This effect can also be achieved
-using the asm labels extension (@pxref{Asm Labels}).
+assembly for a given declaration. While this pragma is supported on all
+platforms, it is intended primarily to provide compatibility with the
+Solaris system headers. This effect can also be achieved using the asm
+labels extension (@pxref{Asm Labels}).

7) (Loop-Specific Pragmas) Grammar error.

-dependencies which would prevent that consecutive iterations of
-the following loop can be executed concurrently with SIMD
+dependencies which would prevent consecutive iterations of
+the following loop from executing concurrently with SIMD

8) In invoke.texi (i386 and x86-64 Options) List -masm dialects in dialect order.

-Output assembly instructions using selected @var{dialect}. Supported
-choices are @samp{intel} or @samp{att} (the default).  Darwin does
+Output assembly instructions using selected @var{dialect}.  Also affects
+which dialect is used for Basic @code{asm} (@pxref{Basic Asm}) and
+Extended @code{asm} (@pxref{Extended Asm}). Supported choices (in Dialect
+order) are @samp{att} or @samp{intel}. The default is @samp{att}. Darwin does

FWIW,
dw


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