[PATCH][doc] Improve pipeline description docs a bit

[PATCH][doc] Improve pipeline description docs a bit

[Kyrill Tkachov]

[-- Attachment #1: Type: text/plain, Size: 512 bytes --]

Hi all,

This patch attempts to improve the pipeline description documentation.
It fixes some grammar errors,typos and clarifies some concepts.

The sections on the syntactic constructs are formatted to have a
small description, and example, description of syntax elements and some
elaboration.

Is this ok for trunk?

Thanks,
Kyrill

2014-04-20  Kyrylo Tkachov  <kyrylo.tkachov@arm.com>

	* doc/md.texi (Specifying processor pipeline description):
	Improve wording.
	Clarify some constructs.

[-- Attachment #2: doc-md-texi.patch --]
[-- Type: application/octet-stream, Size: 25839 bytes --]

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index f2c25c2..95bc032 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -8655,110 +8655,105 @@ processors) have many @dfn{functional units} on which several
 instructions can be executed simultaneously.  An instruction starts
 execution if its issue conditions are satisfied.  If not, the
 instruction is stalled until its conditions are satisfied.  Such
-@dfn{interlock (pipeline) delay} causes interruption of the fetching
-of successor instructions (or demands nop instructions, e.g.@: for some
-MIPS processors).
+@dfn{interlock (pipeline) delays} reduce the throughput of a processor
+(or require issuing nop instructions, e.g.@: for some MIPS processors).
 
 There are two major kinds of interlock delays in modern processors.
 The first one is a data dependence delay determining @dfn{instruction
-latency time}.  The instruction execution is not started until all
-source data have been evaluated by prior instructions (there are more
-complex cases when the instruction execution starts even when the data
-are not available but will be ready in given time after the
-instruction execution start).  Taking the data dependence delays into
-account is simple.  The data dependence (true, output, and
-anti-dependence) delay between two instructions is given by a
-constant.  In most cases this approach is adequate.  The second kind
-of interlock delays is a reservation delay.  The reservation delay
-means that two instructions under execution will be in need of shared
-processors resources, i.e.@: buses, internal registers, and/or
+latency time}.  Instructions may not complete execution until all inputs
+to the instruction have been evaluated and are available for use.
+Taking data dependence delays into account is simple.
+The data dependence (true, output, and anti-dependence) delay between two
+instructions is modelled as being constant.  In most cases this approach is
+adequate.  The second kind of interlock delays is a reservation delay.
+The reservation delay means that two or more executing instructions will require
+shared processor resources, i.e.@: buses, internal registers, and/or
 functional units, which are reserved for some time.  Taking this kind
-of delay into account is complex especially for modern @acronym{RISC}
+of delay into account is complex, especially for modern @acronym{RISC}
 processors.
 
-The task of exploiting more processor parallelism is solved by an
+The compiler tries to exploit instruction level parallelism by using an
 instruction scheduler.  For a better solution to this problem, the
 instruction scheduler has to have an adequate description of the
-processor parallelism (or @dfn{pipeline description}).  GCC
+resources in the processor (called a @dfn{pipeline description}).  GCC
 machine descriptions describe processor parallelism and functional
 unit reservations for groups of instructions with the aid of
 @dfn{regular expressions}.
 
 The GCC instruction scheduler uses a @dfn{pipeline hazard recognizer} to
-figure out the possibility of the instruction issue by the processor
-on a given simulated processor cycle.  The pipeline hazard recognizer is
-automatically generated from the processor pipeline description.  The
-pipeline hazard recognizer generated from the machine description
-is based on a deterministic finite state automaton (@acronym{DFA}):
-the instruction issue is possible if there is a transition from one
+calculate the profitability of issuing a given instruction on a given
+simulated cycle.  The pipeline hazard recognizer is automatically generated
+from the processor pipeline description.  It is based on a deterministic
+finite state automaton (@acronym{DFA}):
+an instruction can be issued if there exists a transition from one
 automaton state to another one.  This algorithm is very fast, and
 furthermore, its speed is not dependent on processor
 complexity@footnote{However, the size of the automaton depends on
 processor complexity.  To limit this effect, machine descriptions
 can split orthogonal parts of the machine description among several
-automata: but then, since each of these must be stepped independently,
+automata: but then, since each of these must be simulated independently,
 this does cause a small decrease in the algorithm's performance.}.
 
 @cindex automaton based pipeline description
-The rest of this section describes the directives that constitute
+The rest of this section describes the directives that can be used to define
 an automaton-based processor pipeline description.  The order of
-these constructions within the machine description file is not
+these constructs within the machine description file is not
 important.
 
 @findex define_automaton
 @cindex pipeline hazard recognizer
-The following optional construction describes names of automata
-generated and used for the pipeline hazards recognition.  Sometimes
-the generated finite state automaton used by the pipeline hazard
-recognizer is large.  If we use more than one automaton and bind functional
-units to the automata, the total size of the automata is usually
-less than the size of the single automaton.  If there is no one such
-construction, only one finite state automaton is generated.
+
+The define_automaton construct declares the names of automata.
+It takes the following form:
 
 @smallexample
 (define_automaton @var{automata-names})
 @end smallexample
 
 @var{automata-names} is a string giving names of the automata.  The
-names are separated by commas.  All the automata should have unique names.
-The automaton name is used in the constructions @code{define_cpu_unit} and
-@code{define_query_cpu_unit}.
+names are separated by commas.  All the automata must have unique names.
+The automaton name is used to bind @code{define_cpu_unit} and
+@code{define_query_cpu_unit} constructs to specific automata.
+
+This construct declares the names of automata.
+Sometimes the generated finite state automaton is too large.
+This can be mitigated by defining more than one automaton (e.g. one for each
+microarchitecture) and binding functional units to each automaton.  Using this
+approach the sum of the sizes of the resulting automata is usually smaller than
+the size of the large automaton.  If this construct is not used anywhere, only
+one finite state automaton is generated.
 
 @findex define_cpu_unit
 @cindex processor functional units
-Each processor functional unit used in the description of instruction
-reservations should be described by the following construction.
+Each functional unit of the processor used in the description of instruction
+reservations should be described by constructs of the following form:
 
 @smallexample
 (define_cpu_unit @var{unit-names} [@var{automaton-name}])
 @end smallexample
 
 @var{unit-names} is a string giving the names of the functional units
-separated by commas.  Don't use name @samp{nothing}, it is reserved
-for other goals.
+separated by commas.  Using name @samp{nothing} is not allowed,
+it is a reserved name used elsewhere.
 
-@var{automaton-name} is a string giving the name of the automaton with
-which the unit is bound.  The automaton should be described in
-construction @code{define_automaton}.  You should give
-@dfn{automaton-name}, if there is a defined automaton.
+@var{automaton-name} is a string giving the name of the automaton to
+which the unit belongs.  The automaton should have been declared using
+@code{define_automaton}.
 
-The assignment of units to automata are constrained by the uses of the
+The assignment of units to automata is constrained by the uses of the
 units in insn reservations.  The most important constraint is: if a
 unit reservation is present on a particular cycle of an alternative
 for an insn reservation, then some unit from the same automaton must
 be present on the same cycle for the other alternatives of the insn
 reservation.  The rest of the constraints are mentioned in the
-description of the subsequent constructions.
+description of the subsequent constructs.
 
 @findex define_query_cpu_unit
 @cindex querying function unit reservations
-The following construction describes CPU functional units analogously
-to @code{define_cpu_unit}.  The reservation of such units can be
-queried for an automaton state.  The instruction scheduler never
-queries reservation of functional units for given automaton state.  So
-as a rule, you don't need this construction.  This construction could
-be used for future code generation goals (e.g.@: to generate
-@acronym{VLIW} insn templates).
+
+The define_query_cpu_unit construct can be used to define units
+that query the automaton state when reserved.  Their definition
+is similar to @code{define_cpu_unit}:
 
 @smallexample
 (define_query_cpu_unit @var{unit-names} [@var{automaton-name}])
@@ -8767,50 +8762,55 @@ be used for future code generation goals (e.g.@: to generate
 @var{unit-names} is a string giving names of the functional units
 separated by commas.
 
-@var{automaton-name} is a string giving the name of the automaton with
+@var{automaton-name} is a string giving the name of the automaton to
 which the unit is bound.
 
+The reservation of such units can be queried for an automaton state.
+Currently the instruction scheduler never queries the reservation
+of functional units for a given automaton state.
+Thus, this construct isn't used presently but it could have potential
+uses in the fugure (e.g.@: to generate @acronym{VLIW} insn templates).
+
+
 @findex define_insn_reservation
 @cindex instruction latency time
 @cindex regular expressions
 @cindex data bypass
-The following construction is the major one to describe pipeline
-characteristics of an instruction.
+The following construct is the most important one used to describe the
+pipeline characteristics of an instruction:
 
 @smallexample
 (define_insn_reservation @var{insn-name} @var{default_latency}
                          @var{condition} @var{regexp})
 @end smallexample
 
-@var{default_latency} is a number giving latency time of the
+@var{default_latency} is a number giving the latency of the
 instruction.  There is an important difference between the old
 description and the automaton based pipeline description.  The latency
-time is used for all dependencies when we use the old description.  In
-the automaton based pipeline description, the given latency time is only
-used for true dependencies.  The cost of anti-dependencies is always
-zero and the cost of output dependencies is the difference between
-latency times of the producing and consuming insns (if the difference
-is negative, the cost is considered to be zero).  You can always
-change the default costs for any description by using the target hook
+is used for all types of dependencies when we used the old description.  In
+the automaton based pipeline description, the  latency is only taken into
+account when analysing true dependencies (i.e. not output or
+anti-dependencies).  The cost of anti-dependencies is always zero and the
+cost of output dependencies is the difference between the latencies
+of the producing and consuming insns (if the difference is negative, the
+cost is considered to be zero).  You can always change the default cost
+between any pair of insns by using the target hook
 @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).
 
 @var{insn-name} is a string giving the internal name of the insn.  The
-internal names are used in constructions @code{define_bypass} and in
+internal names are used in the @code{define_bypass} construct and in
 the automaton description file generated for debugging.  The internal
-name has nothing in common with the names in @code{define_insn}.  It is a
+name has nothing in common with the names in @code{define_insn}.  It is
 good practice to use insn classes described in the processor manual.
 
 @var{condition} defines what RTL insns are described by this
-construction.  You should remember that you will be in trouble if
-@var{condition} for two or more different
-@code{define_insn_reservation} constructions is TRUE for an insn.  In
-this case what reservation will be used for the insn is not defined.
-Such cases are not checked during generation of the pipeline hazards
-recognizer because in general recognizing that two conditions may have
-the same value is quite difficult (especially if the conditions
-contain @code{symbol_ref}).  It is also not checked during the
-pipeline hazard recognizer work because it would slow down the
-recognizer considerably.
+construct.  You must avoid having more than one
+@code{define_insn_reservation} matching any one RTL insn, as the behaviour is
+then not defined.  Such cases are not checked during the generation of the
+automaton because in general recognizing that two conditions may have
+the same value is quite difficult (especially if the conditions contain
+@code{symbol_ref}).  It is also not checked during runtime because it would
+slow down the recognizer considerably.
 
 @var{regexp} is a string describing the reservation of the cpu's functional
 units by the instruction.  The reservations are described by a regular
@@ -8854,39 +8854,42 @@ second regular expression @strong{and} etc.
 @item
 @samp{*} is used for convenience and simply means a sequence in which
 the regular expression are repeated @var{number} times with cycle
-advancing (see @samp{,}).
+advancing (see @samp{,}).  For example: @code{unit0*2} is equivalent to
+@code{unit0,unit0}.
 
 @item
 @samp{cpu_function_unit_name} denotes reservation of the named
 functional unit.
 
 @item
-@samp{reservation_name} --- see description of construction
+@samp{reservation_name} --- see description of construct
 @samp{define_reservation}.
 
 @item
-@samp{nothing} denotes no unit reservations.
+@samp{nothing} denotes no unit reservations.  @samp{nothing} is reserved for
+use here and therefore should not be used for any other purpose in the pipeline
+description.
 @end itemize
 
 @findex define_reservation
 Sometimes unit reservations for different insns contain common parts.
 In such case, you can simplify the pipeline description by describing
-the common part by the following construction
+the common part by the following construct
 
 @smallexample
 (define_reservation @var{reservation-name} @var{regexp})
 @end smallexample
 
-@var{reservation-name} is a string giving name of @var{regexp}.
-Functional unit names and reservation names are in the same name
-space.  So the reservation names should be different from the
+@var{reservation-name} is a string giving a name to the regular expression
+@var{regexp}. Functional unit names and reservation names are in the same name
+space.  Therefore the reservation names should be different from the
 functional unit names and can not be the reserved name @samp{nothing}.
 
 @findex define_bypass
 @cindex instruction latency time
 @cindex data bypass
-The following construction is used to describe exceptions in the
-latency time for given instruction pair.  This is so called bypasses.
+The following construct is used to describe a bypass i.e. an exception
+in the execution latency between a pair of instructions:
 
 @smallexample
 (define_bypass @var{number} @var{out_insn_names} @var{in_insn_names}
@@ -8907,16 +8910,17 @@ defines a bypass between instructions that start with
 @samp{cpu1_load_}.
 
 @var{guard} is an optional string giving the name of a C function which
-defines an additional guard for the bypass.  The function will get the
+defines an additional guard for the bypass.  The function will take the
 two insns as parameters.  If the function returns zero the bypass will
 be ignored for this case.  The additional guard is necessary to
-recognize complicated bypasses, e.g.@: when the consumer is only an address
-of insn @samp{store} (not a stored value).
+recognize complicated bypasses, e.g.@: when the consumer is an address
+used in a @samp{store} insn rather than the stored value.
 
-If there are more one bypass with the same output and input insns, the
-chosen bypass is the first bypass with a guard in description whose
-guard function returns nonzero.  If there is no such bypass, then
-bypass without the guard function is chosen.
+If there is more one bypass with the same output and input insns, the
+chosen bypass is the first bypass with a guard function in its definition that
+returns nonzero.  If there is no such bypass, then a bypass without a guard
+function is chosen.  These constructs can be used to describe, for example,
+forwarding paths in a processor pipeline.
 
 @findex exclusion_set
 @findex presence_set
@@ -8925,8 +8929,8 @@ bypass without the guard function is chosen.
 @findex final_absence_set
 @cindex VLIW
 @cindex RISC
-The following five constructions are usually used to describe
-@acronym{VLIW} processors, or more precisely, to describe a placement
+The following five constructs are usually used to describe
+@acronym{VLIW} processors, or more precisely, to describe the placement
 of small instructions into @acronym{VLIW} instruction slots.  They
 can be used for @acronym{RISC} processors, too.
 
@@ -8938,50 +8942,55 @@ can be used for @acronym{RISC} processors, too.
 (final_absence_set @var{unit-names} @var{patterns})
 @end smallexample
 
-@var{unit-names} is a string giving names of functional units
-separated by commas.
+@var{unit-names} is a comma-separated string giving the names of functional
+units.
 
-@var{patterns} is a string giving patterns of functional units
-separated by comma.  Currently pattern is one unit or units
-separated by white-spaces.
+@var{patterns} is a comma-separated string specifying the patterns of
+functional units.  Each pattern can be the name of a functional unit or a
+whitespace-separated list of functional units.  This is described by the
+following simple syntax:
+
+@smallexample
+patterns = pattern "," pattern
+
+pattern = cpu_function_unit_name cpu_function_unit_name
+          | cpu_function_unit_name
+@end smallexample
 
-The first construction (@samp{exclusion_set}) means that each
+The first construct (@samp{exclusion_set}) means that each
 functional unit in the first string can not be reserved simultaneously
 with a unit whose name is in the second string and vice versa.  For
-example, the construction is useful for describing processors
+example, the construct is useful for describing processors
 (e.g.@: some SPARC processors) with a fully pipelined floating point
-functional unit which can execute simultaneously only single floating
+functional unit which at any given point can execute only single floating
 point insns or only double floating point insns.
 
-The second construction (@samp{presence_set}) means that each
-functional unit in the first string can not be reserved unless at
-least one of pattern of units whose names are in the second string is
-reserved.  This is an asymmetric relation.  For example, it is useful
-for description that @acronym{VLIW} @samp{slot1} is reserved after
-@samp{slot0} reservation.  We could describe it by the following
-construction
+The second construct (@samp{presence_set}) means that each functional
+unit in the first string can not be reserved unless at least one of the
+units whose names match any of the patterns in the second string is reserved.
+This is an asymmetric relation.  For example, we want to describe that
+@acronym{VLIW} @samp{slot1} is reserved after @samp{slot0}.  We can do
+that as follows
 
 @smallexample
 (presence_set "slot1" "slot0")
 @end smallexample
 
 Or @samp{slot1} is reserved only after @samp{slot0} and unit @samp{b0}
-reservation.  In this case we could write
+are reserved.  In this case we could write
 
 @smallexample
 (presence_set "slot1" "slot0 b0")
 @end smallexample
 
-The third construction (@samp{final_presence_set}) is analogous to
-@samp{presence_set}.  The difference between them is when checking is
-done.  When an instruction is issued in given automaton state
-reflecting all current and planned unit reservations, the automaton
-state is changed.  The first state is a source state, the second one
-is a result state.  Checking for @samp{presence_set} is done on the
-source state reservation, checking for @samp{final_presence_set} is
-done on the result reservation.  This construction is useful to
-describe a reservation which is actually two subsequent reservations.
-For example, if we use
+The third construct (@samp{final_presence_set}) is analogous to
+@samp{presence_set}.  The difference is when the checking is
+done.  @samp{presence_set} is checked against the automaton state
+before issuing an instruction (and performing a state transition).
+@samp{final_presence_set} is checked against the resulting state after
+the state transition resulting from issuing the instruction.
+This is useful to describe a reservation which is actually two
+subsequent reservations.  For example, if we use
 
 @smallexample
 (presence_set "slot1" "slot0")
@@ -8994,9 +9003,9 @@ the following insn will be never issued (because @samp{slot1} requires
 (define_reservation "insn_and_nop" "slot0 + slot1")
 @end smallexample
 
-but it can be issued if we use analogous @samp{final_presence_set}.
+but it can be issued if we use the analogous @samp{final_presence_set}.
 
-The forth construction (@samp{absence_set}) means that each functional
+The fourth construct (@samp{absence_set}) means that each functional
 unit in the first string can be reserved only if each pattern of units
 whose names are in the second string is not reserved.  This is an
 asymmetric relation (actually @samp{exclusion_set} is analogous to
@@ -9020,7 +9029,7 @@ this case we could write
 All functional units mentioned in a set should belong to the same
 automaton.
 
-The last construction (@samp{final_absence_set}) is analogous to
+The last construct (@samp{final_absence_set}) is analogous to
 @samp{absence_set} but checking is done on the result (state)
 reservation.  See comments for @samp{final_presence_set}.
 
@@ -9029,37 +9038,36 @@ reservation.  See comments for @samp{final_presence_set}.
 @cindex nondeterministic finite state automaton
 @cindex finite state automaton minimization
 You can control the generator of the pipeline hazard recognizer with
-the following construction.
+the following construct.
 
 @smallexample
 (automata_option @var{options})
 @end smallexample
 
-@var{options} is a string giving options which affect the generated
-code.  Currently there are the following options:
+@var{options} is a string giving specifying an option.
+Currently the following options are available:
 
 @itemize @bullet
 @item
 @dfn{no-minimization} makes no minimization of the automaton.  This is
-only worth to do when we are debugging the description and need to
-look more accurately at reservations of states.
+only worth doing when we are debugging the description and need to
+look more accurately at the reservations of states.
 
 @item
-@dfn{time} means printing time statistics about the generation of
-automata.
+@dfn{time} causes time statistics about the automata generation process to
+be printed during build time.
 
 @item
-@dfn{stats} means printing statistics about the generated automata
-such as the number of DFA states, NDFA states and arcs.
+@dfn{stats} causes statistics about the generated automata such as the
+number of DFA states, NDFA states and arcs to be printed during the build.
 
 @item
-@dfn{v} means a generation of the file describing the result automata.
-The file has suffix @samp{.dfa} and can be used for the description
-verification and debugging.
+@dfn{v} causes the generation, in the build directory, of a file describing
+the resulting automata.  The file has suffix @samp{.dfa} and can be useful
+for verification and debugging of the description.
 
 @item
-@dfn{w} means a generation of warning instead of error for
-non-critical errors.
+@dfn{w} relaxes non-critical errors into warnings instead.
 
 @item
 @dfn{no-comb-vect} prevents the automaton generator from generating
@@ -9096,8 +9104,8 @@ huge automaton.
 @end itemize
 
 As an example, consider a superscalar @acronym{RISC} machine which can
-issue three insns (two integer insns and one floating point insn) on
-the cycle but can finish only two insns.  To describe this, we define
+issue three insns (two integer insns and one floating point insn) per
+cycle but can retire only two insns.  To describe this, we define
 the following functional units.
 
 @smallexample
@@ -9110,10 +9118,10 @@ their result is ready in two cycles.  The simple integer insns are
 issued into the first pipeline unless it is reserved, otherwise they
 are issued into the second pipeline.  Integer division and
 multiplication insns can be executed only in the second integer
-pipeline and their results are ready correspondingly in 8 and 4
-cycles.  The integer division is not pipelined, i.e.@: the subsequent
+pipeline and their results are ready in 8 and 4
+cycles respectively.  Integer division is not pipelined, i.e.@: a subsequent
 integer division insn can not be issued until the current division
-insn finished.  Floating point insns are fully pipelined and their
+insn is finished.  Floating point insns are fully pipelined and their
 results are ready in 3 cycles.  Where the result of a floating point
 insn is used by an integer insn, an additional delay of one cycle is
 incurred.  To describe all of this we could specify
@@ -9142,8 +9150,7 @@ To simplify the description we could describe the following reservation
 (define_reservation "finish" "port0|port1")
 @end smallexample
 
-and use it in all @code{define_insn_reservation} as in the following
-construction
+and use it in all @code{define_insn_reservation} constructs as follows
 
 @smallexample
 (define_insn_reservation "simple" 2 (eq_attr "type" "int")

Re: [PATCH][doc] Improve pipeline description docs a bit

[Sandra Loosemore]

On 04/20/2015 04:31 AM, Kyrill Tkachov wrote:
> Hi all,
>
> This patch attempts to improve the pipeline description documentation.
> It fixes some grammar errors,typos and clarifies some concepts.
>
> The sections on the syntactic constructs are formatted to have a
> small description, and example, description of syntax elements and some
> elaboration.
>
> Is this ok for trunk?
>
> Thanks,
> Kyrill
>
> 2014-04-20  Kyrylo Tkachov  <kyrylo.tkachov@arm.com>
>
> 	* doc/md.texi (Specifying processor pipeline description):
> 	Improve wording.
> 	Clarify some constructs.

Hmmmm.  I guess overall this is an improvement, but I still see quite a 
few things that need tweaking (and I wasn't even looking very hard).

> +latency time}.  Instructions may not complete execution until all inputs
> +to the instruction have been evaluated and are available for use.
> +Taking data dependence delays into account is simple.

I don't think the above sentence adds anything and could be deleted.

> +The data dependence (true, output, and anti-dependence) delay between two
> +instructions is modelled as being constant.  In most cases this approach is
> +adequate.  The second kind of interlock delays is a reservation delay.
> +The reservation delay means that two or more executing instructions will require

s/will require/require/

> +
> +The define_automaton construct declares the names of automata.
> +It takes the following form:
>
>  @smallexample
>  (define_automaton @var{automata-names})
>  @end smallexample
>
>  @var{automata-names} is a string giving names of the automata.  The
> -names are separated by commas.  All the automata should have unique names.
> -The automaton name is used in the constructions @code{define_cpu_unit} and
> -@code{define_query_cpu_unit}.
> +names are separated by commas.  All the automata must have unique names.
> +The automaton name is used to bind @code{define_cpu_unit} and
> +@code{define_query_cpu_unit} constructs to specific automata.
> +
> +This construct declares the names of automata.

You already said that a few sentences above; delete this one.

> +The define_query_cpu_unit construct can be used to define units

Add @code{} markup here.

> -@var{default_latency} is a number giving latency time of the
> +@var{default_latency} is a number giving the latency of the
>  instruction.  There is an important difference between the old
>  description and the automaton based pipeline description.  The latency
> -time is used for all dependencies when we use the old description.  In
> -the automaton based pipeline description, the given latency time is only
> -used for true dependencies.  The cost of anti-dependencies is always
> -zero and the cost of output dependencies is the difference between
> -latency times of the producing and consuming insns (if the difference
> -is negative, the cost is considered to be zero).  You can always
> -change the default costs for any description by using the target hook
> +is used for all types of dependencies when we used the old description.  In
> +the automaton based pipeline description, the  latency is only taken into
> +account when analysing true dependencies (i.e. not output or
> +anti-dependencies).  The cost of anti-dependencies is always zero and the
> +cost of output dependencies is the difference between the latencies
> +of the producing and consuming insns (if the difference is negative, the
> +cost is considered to be zero).  You can always change the default cost
> +between any pair of insns by using the target hook
>  @code{TARGET_SCHED_ADJUST_COST} (@pxref{Scheduling}).

Here I am confused.  What is the "old description"?  If this is a 
leftover of some obsolete way of doing things, the references to it 
should be deleted.

> +construct.  You must avoid having more than one
> +@code{define_insn_reservation} matching any one RTL insn, as the behaviour is

s/behaviour/behavior/

> +The following construct is used to describe a bypass i.e. an exception
> +in the execution latency between a pair of instructions:

@dfn{bypass} ??

>  @var{guard} is an optional string giving the name of a C function which
> -defines an additional guard for the bypass.  The function will get the
> +defines an additional guard for the bypass.  The function will take the
>  two insns as parameters.  If the function returns zero the bypass will
>  be ignored for this case.  The additional guard is necessary to

s/will take/takes/
s/will be ignored/is ignored/

> +If there is more one bypass with the same output and input insns, the
> +chosen bypass is the first bypass with a guard function in its definition that
> +returns nonzero.  If there is no such bypass, then a bypass without a guard
> +function is chosen.  These constructs can be used to describe, for example,
> +forwarding paths in a processor pipeline.

I don't understand what the last sentence has to do with the rest of 
this paragraph.  If this is part of the general discussion of what 
define_bypass does, it should be moved up to the paragraph where the 
concept of a bypass is introduced.

> -@var{unit-names} is a string giving names of functional units
> -separated by commas.
> +@var{unit-names} is a comma-separated string giving the names of functional
> +units.

Looking at examples, I think the original text is less confusing:  it is 
a string in which the names are separated by commas.

> -@var{patterns} is a string giving patterns of functional units
> -separated by comma.  Currently pattern is one unit or units
> -separated by white-spaces.
> +@var{patterns} is a comma-separated string specifying the patterns of
> +functional units.  Each pattern can be the name of a functional unit or a
> +whitespace-separated list of functional units.  This is described by the
> +following simple syntax:
> +
> +@smallexample
> +patterns = pattern "," pattern
> +
> +pattern = cpu_function_unit_name cpu_function_unit_name
> +          | cpu_function_unit_name
> +@end smallexample

I'm not sure this is an improvement either.  How about

@var{patterns} is a string specifying a list of patterns of functional 
units.  Patterns in the list are separated by commas.  Each pattern can 
be the name of a functional unit or a whitespace-separated list of 
functional unit names.

> -The first construction (@samp{exclusion_set}) means that each
> +The first construct (@samp{exclusion_set}) means that each

Here I'd just say

The @code{exclusion_set} construct means that each

and likewise for the second, etc of this enumeration.  Also note that 
all the markup on these names should be @code rather than @samp.

> -@var{options} is a string giving options which affect the generated
> -code.  Currently there are the following options:
> +@var{options} is a string giving specifying an option.
> +Currently the following options are available:

Does the implementation in fact recognize multiple options here?  If 
it's only a single option, we should use "@var{option}" here.  (It looks 
like all existing uses specify only a single option.)

And in the descriptions of the individual options, e.g.

>  @itemize @bullet
>  @item
>  @dfn{no-minimization} makes no minimization of the automaton.  This is
> -only worth to do when we are debugging the description and need to
> -look more accurately at reservations of states.
> +only worth doing when we are debugging the description and need to
> +look more accurately at the reservations of states.

These are constant strings and should be marked up as e.g. 
@code{"no-minimization"} instead of using @dfn{} markup.

-Sandra