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
