From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by sourceware.org (Postfix) with ESMTP id D74E73858CDB for ; Sun, 5 Nov 2023 18:46:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org D74E73858CDB Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=arm.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=arm.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org D74E73858CDB Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=217.140.110.172 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699209983; cv=none; b=HZJ6c2/I7Y4Ixg9/K10hTPlI7x4iD78QM0EuwzyoYTskULGrMtzhTy4yCSK6KpjNETa6zKb5JnG9kg616NjNVVvUV+JfN3xuQm8abKMECNgbcT+cT3dkJHmfTp3VutenPD5kccCSMJq6uFShI/3eiGC79O8ZMymzMyp9CWd2U/E= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1699209983; c=relaxed/simple; bh=exSmabGHEnDNHmo4Tqso7Zpv01B77MgPy9ko2ul2j2I=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=tQ5xshM0D8VXHoOjrkeb64quGm6FgTLFbSB6DbXHQyCb2b41b5GGhRd6phBp1R5Z+nAkXYYddwq8k5x+dTl3LtwT/7OQBnt5RJBETNIO7/iU5xtq4l9xNYL6Vxv9lrU2J/CjDG2ELsVCSrNWUa3MM2gLtMunRS9ohHOWGK9d5+k= ARC-Authentication-Results: i=1; server2.sourceware.org Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 57A8BC15; Sun, 5 Nov 2023 10:47:04 -0800 (PST) Received: from localhost (e121540-lin.manchester.arm.com [10.32.110.72]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 13AC13F703; Sun, 5 Nov 2023 10:46:19 -0800 (PST) From: Richard Sandiford To: gcc-patches@gcc.gnu.org Mail-Followup-To: gcc-patches@gcc.gnu.org,jlaw@ventanamicro.com, richard.sandiford@arm.com Cc: jlaw@ventanamicro.com Subject: [PATCH 01/12] mode-switching: Tweak the macro/hook documentation References: Date: Sun, 05 Nov 2023 18:46:18 +0000 In-Reply-To: (Richard Sandiford's message of "Sun, 05 Nov 2023 18:45:29 +0000") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Status: No, score=-23.4 required=5.0 tests=BAYES_00,GIT_PATCH_0,KAM_DMARC_NONE,KAM_DMARC_STATUS,KAM_LAZY_DOMAIN_SECURITY,SPF_HELO_NONE,SPF_NONE,TXREP,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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 f7ac806ff15..759331a2c96 100644 --- a/gcc/doc/tm.texi +++ b/gcc/doc/tm.texi @@ -10368,7 +10368,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, @@ -10378,73 +10378,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 141027e0bb4..a7b7aa289d8 100644 --- a/gcc/doc/tm.texi.in +++ b/gcc/doc/tm.texi.in @@ -6932,7 +6932,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, @@ -6942,27 +6942,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 42622177ef9..3dae33522f1 100644 --- a/gcc/target.def +++ b/gcc/target.def @@ -7020,51 +7020,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.25.1