diff mbox series

[gcn] install.texi: Update for new ISA targets and their requirements

Message ID b93b0092-1c0c-40e8-8b4a-a1cab9068c62@baylibre.com
State New
Headers
Series [gcn] install.texi: Update for new ISA targets and their requirements |

Checks

Context Check Description
linaro-tcwg-bot/tcwg_gcc_build--master-aarch64 success Build passed
linaro-tcwg-bot/tcwg_simplebootstrap_build--master-aarch64-bootstrap success Build passed
linaro-tcwg-bot/tcwg_gcc_check--master-aarch64 fail Patch failed to apply
linaro-tcwg-bot/tcwg_simplebootstrap_build--master-arm-bootstrap fail Patch failed to apply
linaro-tcwg-bot/tcwg_gcc_build--master-arm fail Patch failed to apply

Commit Message

Tobias Burnus Feb. 10, 2025, 3:50 p.m. UTC 
  Update the GCN install documentation for added ISAs, especially
as no longer all supported ISA are enabled by default.  And for
the (ROCm wise: upcoming) generic support.

OK for mainline?

Tobias

Comments

Sandra Loosemore Feb. 10, 2025, 4:05 p.m. UTC | #1 
On 2/10/25 08:50, Tobias Burnus wrote:
> Update the GCN install documentation for added ISAs, especially
> as no longer all supported ISA are enabled by default.  And for
> the (ROCm wise: upcoming) generic support.
> 
> OK for mainline?

I have no comments on the technical content, but....

> @@ -3991,14 +3991,35 @@ This is a synonym for @samp{x86_64-*-solaris2*}.
>  @heading amdgcn-*-amdhsa
>  AMD GCN GPU target.
>  
> -Instead of GNU Binutils, you will need to install LLVM 15, or later, and copy
> +Instead of GNU Binutils, you will need to install LLVM and copy

s/you will need/you need/

>  @file{bin/llvm-mc} to @file{amdgcn-amdhsa/bin/as},
>  @file{bin/lld} to @file{amdgcn-amdhsa/bin/ld},
>  @file{bin/llvm-nm} to @file{amdgcn-amdhsa/bin/nm}, and
>  @file{bin/llvm-ar} to both @file{bin/amdgcn-amdhsa-ar} and
> -@file{bin/amdgcn-amdhsa-ranlib}.  Note that LLVM 13.0.1 or LLVM 14 can be used
> -by specifying a @code{--with-multilib-list=} that does not list @code{gfx1100}
> -and @code{gfx1103}.
> +@file{bin/amdgcn-amdhsa-ranlib}.
> +
> +The required version of LLVM depends on the devices that should be supported.

s/should be supported/you want to support/

> +As the list of ISA is long, GCC by default only builds a subset of the supported

s/ISA/ISAs/

> +ISA as multilib; use @code{--with-multilib-list=} to tailor the built multilibs.

s/ISA as multilib/ISAs as multilibs/

> +Note that mixing ISAs in the same binary is not supported and will give a linker
> +error.

s/will give/gives/

> +
> +By default, multilib support is build for @code{gfx900}, @code{gfx906},

s/is build/is built/

> +@code{gfx908}, @code{gfx90a}, @code{gfx90c}, @code{gfx1030}, @code{gfx1036},
> +@code{gfx1100} and @code{gfx1103}.  The default multilib configuration
> +requires LLVM 15 or newer.  LLVM 13.0.1 or LLVM 14 can be used by specifying
> +a @code{--with-multilib-list=} that does not list any GFX 11 device nor
> +@code{gfx1036}.  At least LLVM 16 is required for @code{gfx1150} and
> +@code{gfx1151}, LLVM 19 for the generic @code{gfx9-generic},
> +@code{gfx10-3-generic}, and @code{gfx11-generic} targets and for
> +@code{gfx1152}, while LLVM 20 is required for @code{gfx1153}.
> +
> +The supported ISA architectures are listed in the GCC manual. The generic
> +ISA targets @code{gfx9-generic}, @code{gfx10-3-generic}, and
> +@code{gfx11-generic} will reduce the number of required multilibs but note

s/will reduce/reduces/

> +that @code{gfx9-generic} does not include @code{gfx908} or @code{gfx90a},
> +that linking specific ISA code is currently not supported, and that only a

Do you mean "linking specific ISA code with generic code"?  (It doesn't 
make much sense to me otherwise.)

> +future ROCm release (newer than 6.3.2) will be able to execute generic code.
>  
>  Use Newlib (4.3.0 or newer; 4.4.0 contains some improvements and 4.5.0 fixes
>  the device console output for GFX10 and GFX11 devices).

-Sandra
Andrew Stubbs Feb. 10, 2025, 4:15 p.m. UTC | #2 
On 10/02/2025 15:50, Tobias Burnus wrote:
> Update the GCN install documentation for added ISAs, especially
> as no longer all supported ISA are enabled by default.  And for
> the (ROCm wise: upcoming) generic support.
> 
> OK for mainline?

> +By default, multilib support is build for @code{gfx900}, @code{gfx906},
> +@code{gfx908}, @code{gfx90a}, @code{gfx90c}, @code{gfx1030}, @code{gfx1036},
> +@code{gfx1100} and @code{gfx1103}.  The default multilib configuration
> +requires LLVM 15 or newer.  LLVM 13.0.1 or LLVM 14 can be used by specifying
> +a @code{--with-multilib-list=} that does not list any GFX 11 device nor
> +@code{gfx1036}.  At least LLVM 16 is required for @code{gfx1150} and
> +@code{gfx1151}, LLVM 19 for the generic @code{gfx9-generic},
> +@code{gfx10-3-generic}, and @code{gfx11-generic} targets and for
> +@code{gfx1152}, while LLVM 20 is required for @code{gfx1153}.

s/build/built/

Otherwise it seems correct to me, if perhaps not exactly poetic.

Andrew
Tobias Burnus Feb. 10, 2025, 4:17 p.m. UTC | #3 
Hi Sandra,

thanks for the careful and quick proofreading; especially, it is good 
that you spotted:

Sandra Loosemore:
>> +that @code{gfx9-generic} does not include @code{gfx908} or 
>> @code{gfx90a},
>> +that linking specific ISA code is currently not supported, and that 
>> only a
>
> Do you mean "linking specific ISA code with generic code"?  (It 
> doesn't make much sense to me otherwise.)

Indeed.

Updated patch attached. – Unless Andrew or someone else has further 
comments or suggestions, I will commit it later today.

Thanks,

Tobias
diff mbox series

Patch

[gcn] install.texi: Update for new ISA targets and their requirements

GCN now supports several additional ISA targets such that no longer
all targets have a multilib by default; add a note about this, the
generic targets and the required LLVM (and ROCm) versions.

gcc/ChangeLog:

	* doc/install.texi (GCN): Update section about multilibs and
	required LLVM version.

 gcc/doc/install.texi | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index 3b9f56b0529..f0c207a3ee7 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -3991,14 +3991,35 @@  This is a synonym for @samp{x86_64-*-solaris2*}.
 @heading amdgcn-*-amdhsa
 AMD GCN GPU target.
 
-Instead of GNU Binutils, you will need to install LLVM 15, or later, and copy
+Instead of GNU Binutils, you will need to install LLVM and copy
 @file{bin/llvm-mc} to @file{amdgcn-amdhsa/bin/as},
 @file{bin/lld} to @file{amdgcn-amdhsa/bin/ld},
 @file{bin/llvm-nm} to @file{amdgcn-amdhsa/bin/nm}, and
 @file{bin/llvm-ar} to both @file{bin/amdgcn-amdhsa-ar} and
-@file{bin/amdgcn-amdhsa-ranlib}.  Note that LLVM 13.0.1 or LLVM 14 can be used
-by specifying a @code{--with-multilib-list=} that does not list @code{gfx1100}
-and @code{gfx1103}.
+@file{bin/amdgcn-amdhsa-ranlib}.
+
+The required version of LLVM depends on the devices that should be supported.
+As the list of ISA is long, GCC by default only builds a subset of the supported
+ISA as multilib; use @code{--with-multilib-list=} to tailor the built multilibs.
+Note that mixing ISAs in the same binary is not supported and will give a linker
+error.
+
+By default, multilib support is build for @code{gfx900}, @code{gfx906},
+@code{gfx908}, @code{gfx90a}, @code{gfx90c}, @code{gfx1030}, @code{gfx1036},
+@code{gfx1100} and @code{gfx1103}.  The default multilib configuration
+requires LLVM 15 or newer.  LLVM 13.0.1 or LLVM 14 can be used by specifying
+a @code{--with-multilib-list=} that does not list any GFX 11 device nor
+@code{gfx1036}.  At least LLVM 16 is required for @code{gfx1150} and
+@code{gfx1151}, LLVM 19 for the generic @code{gfx9-generic},
+@code{gfx10-3-generic}, and @code{gfx11-generic} targets and for
+@code{gfx1152}, while LLVM 20 is required for @code{gfx1153}.
+
+The supported ISA architectures are listed in the GCC manual. The generic
+ISA targets @code{gfx9-generic}, @code{gfx10-3-generic}, and
+@code{gfx11-generic} will reduce the number of required multilibs but note
+that @code{gfx9-generic} does not include @code{gfx908} or @code{gfx90a},
+that linking specific ISA code is currently not supported, and that only a
+future ROCm release (newer than 6.3.2) will be able to execute generic code.
 
 Use Newlib (4.3.0 or newer; 4.4.0 contains some improvements and 4.5.0 fixes
 the device console output for GFX10 and GFX11 devices).