diff options
Diffstat (limited to '0132-Backport-SME-mode-switching-Tweak-the-macro-hook-doc.patch')
| -rw-r--r-- | 0132-Backport-SME-mode-switching-Tweak-the-macro-hook-doc.patch | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/0132-Backport-SME-mode-switching-Tweak-the-macro-hook-doc.patch b/0132-Backport-SME-mode-switching-Tweak-the-macro-hook-doc.patch new file mode 100644 index 0000000..e3c0ff7 --- /dev/null +++ b/0132-Backport-SME-mode-switching-Tweak-the-macro-hook-doc.patch @@ -0,0 +1,311 @@ +From c980e40d2c27ac3ee33c9b6aea6d2b0d4080852e Mon Sep 17 00:00:00 2001 +From: Richard Sandiford <richard.sandiford@arm.com> +Date: Sat, 11 Nov 2023 17:28:54 +0000 +Subject: [PATCH 033/157] [Backport][SME] mode-switching: Tweak the macro/hook + documentation + +Reference: https://gcc.gnu.org/git/?p=gcc.git;a=commit;h=8479a3759025961f80cf0cd6bb3f127e09d0510d + +I found the documentation for the mode-switching macros/hooks +a bit hard to follow at first. This patch tries to add the +information that I think would have made it easier to understand. + +Of course, documentation preferences are personal, and so I could +be changing something that others understood to something that +seems impenetrable. + +Some notes on specific changes: + +- "in an optimizing compilation" didn't seem accurate; the pass + is run even at -O0, and often needs to be for correctness. + +- "at run time" meant when the compiler was run, rather than when + the compiled code was run. + +- Removing the list of optional macros isn't a clarification, + but it means that upcoming patches don't create an absurdly + long list. + +- I don't really understand the purpose of TARGET_MODE_PRIORITY, + so I mostly left that alone. + +gcc/ + * target.def: Tweak documentation of mode-switching hooks. + * doc/tm.texi.in (OPTIMIZE_MODE_SWITCHING): Tweak documentation. + (NUM_MODES_FOR_MODE_SWITCHING): Likewise. + * doc/tm.texi: Regenerate. +--- + gcc/doc/tm.texi | 69 ++++++++++++++++++++++++++++------------------ + gcc/doc/tm.texi.in | 26 +++++++++-------- + gcc/target.def | 43 ++++++++++++++++++----------- + 3 files changed, 84 insertions(+), 54 deletions(-) + +diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi +index 851d31c18..553aa4cf2 100644 +--- a/gcc/doc/tm.texi ++++ b/gcc/doc/tm.texi +@@ -10234,7 +10234,7 @@ The following macros control mode switching optimizations: + + @defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) + Define this macro if the port needs extra instructions inserted for mode +-switching in an optimizing compilation. ++switching. + + For an example, the SH4 can perform both single and double precision + floating point operations, but to perform a single precision operation, +@@ -10244,73 +10244,88 @@ purpose register as a scratch register, hence these FPSCR sets have to + be inserted before reload, i.e.@: you cannot put this into instruction emitting + or @code{TARGET_MACHINE_DEPENDENT_REORG}. + +-You can have multiple entities that are mode-switched, and select at run time +-which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should +-return nonzero for any @var{entity} that needs mode-switching. ++You can have multiple entities that are mode-switched, some of which might ++only be needed conditionally. The entities are identified by their index ++into the @code{NUM_MODES_FOR_MODE_SWITCHING} initializer, with the length ++of the initializer determining the number of entities. ++ ++@code{OPTIMIZE_MODE_SWITCHING} should return nonzero for any @var{entity} ++that needs mode-switching. ++ + If you define this macro, you also have to define + @code{NUM_MODES_FOR_MODE_SWITCHING}, @code{TARGET_MODE_NEEDED}, + @code{TARGET_MODE_PRIORITY} and @code{TARGET_MODE_EMIT}. +-@code{TARGET_MODE_AFTER}, @code{TARGET_MODE_ENTRY}, and @code{TARGET_MODE_EXIT} +-are optional. ++The other macros in this section are optional. + @end defmac + + @defmac NUM_MODES_FOR_MODE_SWITCHING + If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as + initializer for an array of integers. Each initializer element + N refers to an entity that needs mode switching, and specifies the number +-of different modes that might need to be set for this entity. +-The position of the initializer in the initializer---starting counting at ++of different modes that are defined for that entity. ++The position of the element in the initializer---starting counting at + zero---determines the integer that is used to refer to the mode-switched + entity in question. +-In macros that take mode arguments / yield a mode result, modes are +-represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode +-switch is needed / supplied. ++Modes are represented as numbers 0 @dots{} N @minus{} 1. ++In mode arguments and return values, N either represents an unknown ++mode or ``no mode'', depending on context. + @end defmac + + @deftypefn {Target Hook} void TARGET_MODE_EMIT (int @var{entity}, int @var{mode}, int @var{prev_mode}, HARD_REG_SET @var{regs_live}) + Generate one or more insns to set @var{entity} to @var{mode}. + @var{hard_reg_live} is the set of hard registers live at the point where + the insn(s) are to be inserted. @var{prev_moxde} indicates the mode +-to switch from. Sets of a lower numbered entity will be emitted before ++to switch from, or is the number of modes if the previous mode is not ++known. Sets of a lower numbered entity will be emitted before + sets of a higher numbered entity to a mode of the same or lower priority. + @end deftypefn + + @deftypefn {Target Hook} int TARGET_MODE_NEEDED (int @var{entity}, rtx_insn *@var{insn}) + @var{entity} is an integer specifying a mode-switched entity. +-If @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro +-to return an integer value not larger than the corresponding element +-in @code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity} +-must be switched into prior to the execution of @var{insn}. ++If @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this hook ++to return the mode that @var{entity} must be switched into prior to the ++execution of @var{insn}, or the number of modes if @var{insn} has no ++such requirement. + @end deftypefn + + @deftypefn {Target Hook} int TARGET_MODE_AFTER (int @var{entity}, int @var{mode}, rtx_insn *@var{insn}) + @var{entity} is an integer specifying a mode-switched entity. +-If this macro is defined, it is evaluated for every @var{insn} during mode +-switching. It determines the mode that an insn results +-in (if different from the incoming mode). ++If this hook is defined, it is evaluated for every @var{insn} during mode ++switching. It returns the mode that @var{entity} is in after @var{insn} ++has been executed. @var{mode} is the mode that @var{entity} was in ++before @var{insn} was executed, taking account of @var{TARGET_MODE_NEEDED}. ++ ++@var{mode} is equal to the number of modes defined for @var{entity} ++if the mode before @var{insn} is unknown. The hook should likewise return ++the number of modes if it does not know what mode @var{entity} has after ++@var{insn}. ++ ++Not defining the hook is equivalent to returning @var{mode}. + @end deftypefn + + @deftypefn {Target Hook} int TARGET_MODE_ENTRY (int @var{entity}) +-If this macro is defined, it is evaluated for every @var{entity} that +-needs mode switching. It should evaluate to an integer, which is a mode +-that @var{entity} is assumed to be switched to at function entry. ++If this hook is defined, it is evaluated for every @var{entity} that ++needs mode switching. It should return the mode that @var{entity} is ++guaranteed to be in on entry to the function, or the number of modes ++if there is no such guarantee. + If @code{TARGET_MODE_ENTRY} is defined then @code{TARGET_MODE_EXIT} + must be defined. + @end deftypefn + + @deftypefn {Target Hook} int TARGET_MODE_EXIT (int @var{entity}) +-If this macro is defined, it is evaluated for every @var{entity} that +-needs mode switching. It should evaluate to an integer, which is a mode +-that @var{entity} is assumed to be switched to at function exit. ++If this hook is defined, it is evaluated for every @var{entity} that ++needs mode switching. It should return the mode that @var{entity} must ++be in on return from the function, or the number of modes if there is no ++such requirement. + If @code{TARGET_MODE_EXIT} is defined then @code{TARGET_MODE_ENTRY} + must be defined. + @end deftypefn + + @deftypefn {Target Hook} int TARGET_MODE_PRIORITY (int @var{entity}, int @var{n}) +-This macro specifies the order in which modes for @var{entity} ++This hook specifies the order in which modes for @var{entity} + are processed. 0 is the highest priority, + @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the lowest. +-The value of the macro should be an integer designating a mode ++The hook returns an integer designating a mode + for @var{entity}. For any fixed @var{entity}, @code{mode_priority} + (@var{entity}, @var{n}) shall be a bijection in 0 @dots{} + @code{num_modes_for_mode_switching[@var{entity}] - 1}. +diff --git a/gcc/doc/tm.texi.in b/gcc/doc/tm.texi.in +index ac95cdf7a..9ec11b15c 100644 +--- a/gcc/doc/tm.texi.in ++++ b/gcc/doc/tm.texi.in +@@ -6879,7 +6879,7 @@ The following macros control mode switching optimizations: + + @defmac OPTIMIZE_MODE_SWITCHING (@var{entity}) + Define this macro if the port needs extra instructions inserted for mode +-switching in an optimizing compilation. ++switching. + + For an example, the SH4 can perform both single and double precision + floating point operations, but to perform a single precision operation, +@@ -6889,27 +6889,31 @@ purpose register as a scratch register, hence these FPSCR sets have to + be inserted before reload, i.e.@: you cannot put this into instruction emitting + or @code{TARGET_MACHINE_DEPENDENT_REORG}. + +-You can have multiple entities that are mode-switched, and select at run time +-which entities actually need it. @code{OPTIMIZE_MODE_SWITCHING} should +-return nonzero for any @var{entity} that needs mode-switching. ++You can have multiple entities that are mode-switched, some of which might ++only be needed conditionally. The entities are identified by their index ++into the @code{NUM_MODES_FOR_MODE_SWITCHING} initializer, with the length ++of the initializer determining the number of entities. ++ ++@code{OPTIMIZE_MODE_SWITCHING} should return nonzero for any @var{entity} ++that needs mode-switching. ++ + If you define this macro, you also have to define + @code{NUM_MODES_FOR_MODE_SWITCHING}, @code{TARGET_MODE_NEEDED}, + @code{TARGET_MODE_PRIORITY} and @code{TARGET_MODE_EMIT}. +-@code{TARGET_MODE_AFTER}, @code{TARGET_MODE_ENTRY}, and @code{TARGET_MODE_EXIT} +-are optional. ++The other macros in this section are optional. + @end defmac + + @defmac NUM_MODES_FOR_MODE_SWITCHING + If you define @code{OPTIMIZE_MODE_SWITCHING}, you have to define this as + initializer for an array of integers. Each initializer element + N refers to an entity that needs mode switching, and specifies the number +-of different modes that might need to be set for this entity. +-The position of the initializer in the initializer---starting counting at ++of different modes that are defined for that entity. ++The position of the element in the initializer---starting counting at + zero---determines the integer that is used to refer to the mode-switched + entity in question. +-In macros that take mode arguments / yield a mode result, modes are +-represented as numbers 0 @dots{} N @minus{} 1. N is used to specify that no mode +-switch is needed / supplied. ++Modes are represented as numbers 0 @dots{} N @minus{} 1. ++In mode arguments and return values, N either represents an unknown ++mode or ``no mode'', depending on context. + @end defmac + + @hook TARGET_MODE_EMIT +diff --git a/gcc/target.def b/gcc/target.def +index c9bb2b4c2..b87b0f927 100644 +--- a/gcc/target.def ++++ b/gcc/target.def +@@ -6992,51 +6992,62 @@ DEFHOOK + "Generate one or more insns to set @var{entity} to @var{mode}.\n\ + @var{hard_reg_live} is the set of hard registers live at the point where\n\ + the insn(s) are to be inserted. @var{prev_moxde} indicates the mode\n\ +-to switch from. Sets of a lower numbered entity will be emitted before\n\ ++to switch from, or is the number of modes if the previous mode is not\n\ ++known. Sets of a lower numbered entity will be emitted before\n\ + sets of a higher numbered entity to a mode of the same or lower priority.", + void, (int entity, int mode, int prev_mode, HARD_REG_SET regs_live), NULL) + + DEFHOOK + (needed, + "@var{entity} is an integer specifying a mode-switched entity.\n\ +-If @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this macro\n\ +-to return an integer value not larger than the corresponding element\n\ +-in @code{NUM_MODES_FOR_MODE_SWITCHING}, to denote the mode that @var{entity}\n\ +-must be switched into prior to the execution of @var{insn}.", ++If @code{OPTIMIZE_MODE_SWITCHING} is defined, you must define this hook\n\ ++to return the mode that @var{entity} must be switched into prior to the\n\ ++execution of @var{insn}, or the number of modes if @var{insn} has no\n\ ++such requirement.", + int, (int entity, rtx_insn *insn), NULL) + + DEFHOOK + (after, + "@var{entity} is an integer specifying a mode-switched entity.\n\ +-If this macro is defined, it is evaluated for every @var{insn} during mode\n\ +-switching. It determines the mode that an insn results\n\ +-in (if different from the incoming mode).", ++If this hook is defined, it is evaluated for every @var{insn} during mode\n\ ++switching. It returns the mode that @var{entity} is in after @var{insn}\n\ ++has been executed. @var{mode} is the mode that @var{entity} was in\n\ ++before @var{insn} was executed, taking account of @var{TARGET_MODE_NEEDED}.\n\ ++\n\ ++@var{mode} is equal to the number of modes defined for @var{entity}\n\ ++if the mode before @var{insn} is unknown. The hook should likewise return\n\ ++the number of modes if it does not know what mode @var{entity} has after\n\ ++@var{insn}.\n\ ++\n\ ++Not defining the hook is equivalent to returning @var{mode}.", + int, (int entity, int mode, rtx_insn *insn), NULL) + + DEFHOOK + (entry, +- "If this macro is defined, it is evaluated for every @var{entity} that\n\ +-needs mode switching. It should evaluate to an integer, which is a mode\n\ +-that @var{entity} is assumed to be switched to at function entry.\n\ ++ "If this hook is defined, it is evaluated for every @var{entity} that\n\ ++needs mode switching. It should return the mode that @var{entity} is\n\ ++guaranteed to be in on entry to the function, or the number of modes\n\ ++if there is no such guarantee.\n\ + If @code{TARGET_MODE_ENTRY} is defined then @code{TARGET_MODE_EXIT}\n\ + must be defined.", + int, (int entity), NULL) + + DEFHOOK + (exit, +- "If this macro is defined, it is evaluated for every @var{entity} that\n\ +-needs mode switching. It should evaluate to an integer, which is a mode\n\ +-that @var{entity} is assumed to be switched to at function exit.\n\ ++ "If this hook is defined, it is evaluated for every @var{entity} that\n\ ++needs mode switching. It should return the mode that @var{entity} must\n\ ++be in on return from the function, or the number of modes if there is no\n\ ++such requirement.\n\ + If @code{TARGET_MODE_EXIT} is defined then @code{TARGET_MODE_ENTRY}\n\ + must be defined.", + int, (int entity), NULL) + + DEFHOOK + (priority, +- "This macro specifies the order in which modes for @var{entity}\n\ ++ "This hook specifies the order in which modes for @var{entity}\n\ + are processed. 0 is the highest priority,\n\ + @code{NUM_MODES_FOR_MODE_SWITCHING[@var{entity}] - 1} the lowest.\n\ +-The value of the macro should be an integer designating a mode\n\ ++The hook returns an integer designating a mode\n\ + for @var{entity}. For any fixed @var{entity}, @code{mode_priority}\n\ + (@var{entity}, @var{n}) shall be a bijection in 0 @dots{}\n\ + @code{num_modes_for_mode_switching[@var{entity}] - 1}.", +-- +2.33.0 + |