===== Toolchains =====

Alpha/Linux is built with the GNU toolchain: **GCC**, **binutils**, and **glibc**, all of which carry Alpha support in their main development trees. GCC builds the kernel, the C library, and every current distribution. The Alpha-specific parts of the toolchain differ from those of other architectures in three respects: processor selection, the ''-m'' options that have no counterpart on other architectures, and the size limit of the global offset table (GOT). Several newer tools, LLVM above all, have no Alpha support; see [[#not_available_on_alpha|Not available on Alpha]].

Compaq C (''ccc''), a commercial compiler, was also available for Alpha/Linux from 1999; see [[#compaq_c|Compaq C]].

==== GCC ====

Richard Henderson maintains GCC's Alpha back end. [(>[[https://gcc.gnu.org/git/?p=gcc.git;a=blob;f=MAINTAINERS|MAINTAINERS]], GCC)] Upstream GCC's default target is the architecture baseline, so a compiler built without ''--with-cpu'' produces code that runs on every Alpha processor, including those current kernels no longer support.

=== Selecting a processor ===

''-mcpu='' selects both the instruction set and the scheduling model. Values up to ''ev5'' change only scheduling and produce code that runs on every Alpha; ''ev56'' and above add instructions, and their code does not run on earlier processors. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/debian-alpha-mbox/1997-December.mbox#L2007|"Re: :( (about alphaev*)"]], Nikita Schmidt, debian-alpha, 6 Dec 1997)]

^ ''-mcpu'' ^ Processors ^ Adds ^
| ''ev4'', ''ev45'' | 21064, 21064A, 21066, 21068 | baseline |
| ''ev5'' | 21164 | scheduling only |
| ''ev56'' | 21164A | BWX |
| ''pca56'' | 21164PC | BWX, MVI |
| ''ev6'' | 21264 | BWX, MVI, FIX |
| ''ev67'' | 21264A and later | BWX, MVI, FIX, CIX |

GCC has no ''ev68'' value. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/gentoo-alpha-mbox/2005-September.mbox#L1033|"[gentoo-alpha] ev6, ev67 or ev68?"]], Davide Cittaro, gentoo-alpha, 19 Sep 2005)] ''-mcpu=ev67'' is the right choice for the EV68 processors, which add no instructions and schedule like the EV67. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/gentoo-alpha-mbox/2005-September.mbox#L1092|"Re: [gentoo-alpha] ev6, ev67 or ev68?"]], Bryan Østergaard, gentoo-alpha, 19 Sep 2005)] The extensions themselves are described on the [[documentation:instruction_set|Instruction Set]] page.

''-mtune='' takes the same values and changes only instruction scheduling, never the instruction set. The numeric names (''21064'', ''21164a'', ''21264'' and so on) are accepted as synonyms.

Two compatibility issues apply:

  * **An extension may be implemented and still disabled.** Early versions of the PALcode used by MILO left BWX disabled on the AlphaPC 164, so code built with ''-mcpu=ev56'' failed with an illegal instruction on a CPU that implements it; later MILO versions enable it. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/axp-list-mbox/1998-December.mbox#L42672|"Re: egcs and PC164 (ev56 ?)"]], Richard Henderson, axp-list, 18 Dec 1998)]
  * **Binaries built for ev56 do not run on older CPUs.** Linux does not emulate the byte and word instructions; on a pre-EV56 processor they raise an illegal instruction fault and the process receives ''SIGILL''. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/debian-alpha-mbox/2003-May.mbox#L1242|"Re: acrobat reader"]], Falk Hueffner, debian-alpha, 4 May 2003)] See [[documentation:porting:byte_word_access|Byte and Word Access]].

The [[documentation:amask|amask]] instruction reports what the running processor implements.

=== Choosing -mcpu today ===

Linux 6.10 removed support for processors older than the EV56 (21164A), so every system that runs a current kernel implements BWX, and ''-mcpu=ev56'' is the natural baseline for new binaries: it runs on every such system, and avoids the long instruction sequences and the atomicity problems of pre-BWX byte and word access. The kernel's own generic configuration uses ''-mcpu=ev56 -mtune=ev6'', scheduling for the 21264 while staying compatible with the 21164A. [(>[[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/Makefile?h=v7.3-rc1|arch/alpha/Makefile]], Linux 7.3)] A binary built for a specific machine can use that processor's own value, ''-mcpu=ev67'' for a 21264A or later, which adds the FIX, CIX, and MVI instructions.

''-mcpu=ev6'' and ''-mcpu=ev67'' binaries do not run on the 21164A and 21164PC, which the kernel still supports.

=== Distribution baselines ===

Debian's GCC packages have been configured with ''--with-cpu=ev56'' since gcc-13 13.1.0-3 and gcc-12 12.3.0-2, in May 2023, [(>[[https://bugs.debian.org/1036158|Debian bug #1036158]])] [(>[[https://salsa.debian.org/toolchain-team/gcc/-/blob/gcc-15-debian/debian/rules2|debian/rules2]], Debian gcc-15)] after glibc 2.37 removed the legacy hardware capabilities directories and with them the separate EV67 build of glibc. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/debian-alpha-mbox/2023-May.mbox#L1|"Re: future of the libc6.1-alphaev67 package"]], Aurelien Jarno, debian-alpha, 14 May 2023)] An EV67 baseline was also proposed, but owners of pre-EV67 systems objected that they were the majority of working Alphas. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/gentoo-alpha-mbox/gmane-2022-November.mbox#L213|"Re: glibc regression on alpha with 2.34+"]], Frank Scheiner, gentoo-alpha, 20 Nov 2022)]

T2 builds its Alpha images for EV56. [(>[[https://dl.t2sde.org/binary/|dl.t2sde.org/binary]], T2 SDE)] Gentoo's Alpha profile sets no ''-mcpu'', so its stages use the compiler's default, the architecture baseline. [(>[[https://gitweb.gentoo.org/repo/gentoo.git/tree/profiles/arch/alpha/make.defaults|profiles/arch/alpha/make.defaults]], gentoo.git)] The release stages are built by catalyst with its generic ''alpha'' subarchitecture, whose flags are ''-mieee -pipe -O2 -mcpu=ev4''; catalyst also writes them into the stage's ''make.conf''. [(>[[https://gitweb.gentoo.org/proj/catalyst.git/tree/arch/alpha.toml|arch/alpha.toml]], catalyst)] [(>[[https://gitweb.gentoo.org/proj/releng.git/tree/releases/specs-qemu/alpha/stage3-openrc-23.spec|releases/specs-qemu/alpha/stage3-openrc-23.spec]], Gentoo releng)] Code in a stage therefore stores bytes and words with non-atomic pre-BWX sequences (see [[documentation:porting:byte_word_access#atomicity_of_byte_and_word_access|Byte and Word Access]]) until it is rebuilt with a newer ''-mcpu''. Gentoo users choose their own in ''make.conf''; since current kernels need an EV56 or later, ''-mcpu=ev56'' or the processor's own value (see [[#choosing_-mcpu_today|Choosing -mcpu today]]) loses nothing.

=== Alpha-specific options ===

^ Option ^ What it does ^
| ''-mbwx'' / ''-mno-bwx'' | byte/word extension, independently of ''-mcpu'' |
| ''-mcix'' / ''-mno-cix'' | count extension (''CTLZ'', ''CTPOP'', ''CTTZ'') |
| ''-mmax'' / ''-mno-max'' | multimedia extension (MVI) |
| ''-mfix'' / ''-mno-fix'' | square-root and FP convert extension |
| ''-mieee'', ''-mieee-with-inexact'', ''-mieee-conformant'' | software completion, see [[documentation:porting:floating_point|Floating Point]] |
| ''-mtrap-precision='', ''-mfp-rounding-mode='' | trap precision and rounding mode written into each instruction |
| ''-mfp-regs'' / ''-mno-fp-regs'' | whether the FP register file may be used at all. The kernel is built ''-mno-fp-regs'' |
| ''-msmall-data'' / ''-mlarge-data'' | put small objects in ''.sdata'' addressed off the GP, or not |
| ''-msmall-text'' / ''-mlarge-text'' | assume the text segment fits in 4 MiB so calls can be ''BSR'' |
| ''-mexplicit-relocs'' | emit explicit relocations rather than leaving the assembler to macro-expand memory references |
| ''-msafe-bwa'', ''-msafe-partial'' | make byte and word accesses without BWX (''-msafe-bwa''), and piecemeal unaligned and partial-quadword accesses (''-msafe-partial''), thread and signal safe; added in GCC 15 (PR117759) [(>[[https://gcc.gnu.org/bugzilla/show_bug.cgi?id=117759|PR117759]], GCC Bugzilla)] |
| ''-mmemory-latency='' | scheduling assumption for the memory system |

''-mieee'' is the option most often needed. Upstream GCC does not enable it by default, but the Debian and Gentoo GCC packages do. The reasoning, and its cost, are described on the [[documentation:porting:floating_point|Floating Point]] page.

=== "relocation truncated to fit" ===

Alpha addresses global data through the GP register plus a 16-bit signed displacement, so one GOT holds 64 KiB of entries. A link failure such as ''relocation truncated to fit: LITERAL'' means a GOT or small data area has overflowed. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/axp-list-mbox/1996-November.mbox#L43360|"ld reports 'relocation truncated to fit'"]], Topi Kanerva, axp-list, 24 Nov 1996)] The linker splits an application's GOT into multiple subsections, each with its own GP, so ordinary programs do not reach the limit. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/axp-list-mbox/1996-December.mbox#L10307|"linker beta"]], Richard Henderson, axp-list, 6 Dec 1996)]

The limit is still reached in these cases:

  * **''-fpic'' shared libraries.** ''-fpic'' implies ''-msmall-data'', which limits the small data area to 64 KiB; ''-fPIC'' implies ''-mlarge-data'', which does not. A large library that fails to link with ''-fpic'' should be built with ''-fPIC''. [(>[[https://gcc.gnu.org/onlinedocs/gcc/DEC-Alpha-Options.html|DEC Alpha Options]], GCC manual)]
  * **Kernel modules.** The module loader builds one GOT for each module, [(>[[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/arch/alpha/kernel/module.c?h=v7.3-rc1|arch/alpha/kernel/module.c]], Linux 7.3)] and ''R_ALPHA_LITERAL'' relocations "can easily overflow if things get large". A very large driver such as ''radeon'' can fail to load as a module; building it into the kernel avoids the problem. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/gentoo-alpha-mbox/2014-December.mbox#L84|"[gentoo-alpha] Re: radeon questions"]], Måns Rullgård, gentoo-alpha, 9 Dec 2014)]
  * **The kernel itself.** The statically linked kernel has no such diagnostic: an overflowing kernel ''.got'' section produces a kernel that fails at run time rather than at build time. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/axp-list-mbox/2000-April.mbox#L7673|"Re: copy_from_user() kills RH 6.1 kernel"]], Richard Henderson, axp-list, 11 Apr 2000)]

==== binutils ====

The assembler takes ''-mev4'' to ''-mev68'', ''-mpca56'', and ''-mall'' to select the instruction set; the numeric forms (''-m21064'' to ''-m21264b'') also accept the PALcode instructions of that processor. The ''.arch'' directive does the same from within a source file. GCC passes its ''-mcpu'' value to the assembler as the corresponding ''-m'' option. [(>[[https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=gas/config/tc-alpha.c|gas/config/tc-alpha.c]], binutils)] [(>[[https://gcc.gnu.org/git/?p=gcc.git;a=blob;f=gcc/config/alpha/elf.h|gcc/config/alpha/elf.h]], GCC)]

Without one of these options the assembler targets the base architecture, and hand-written assembly is affected in two ways. Instructions from the extensions, such as ''ctpop'', are rejected. The byte and word instructions ''ldbu'', ''ldwu'', ''stb'', ''stw'', ''sextb'', and ''sextw'' are not rejected but treated as macros, and silently expanded into pre-BWX sequences; the expansions of ''stb'' and ''stw'' are non-atomic read-modify-write sequences (see [[documentation:porting:byte_word_access|Byte and Word Access]]). [(>[[https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=gas/config/tc-alpha.c|gas/config/tc-alpha.c]], binutils)] An assembly file that uses byte stores should therefore start with ''.arch ev56'' or be assembled with ''-mcpu=ev56''.

==== GDB ====

GDB supports Alpha/Linux as a native debugger, and can debug Alpha core files and QEMU's gdbstub from another host. [(>[[https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=gdb/alpha-linux-nat.c|gdb/alpha-linux-nat.c]], binutils-gdb)] [(>[[https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=gdb/alpha-linux-tdep.c|gdb/alpha-linux-tdep.c]], binutils-gdb)] ''gdbserver'' has no Alpha support. [(>[[https://sourceware.org/git/?p=binutils-gdb.git;a=blob;f=gdbserver/configure.srv|gdbserver/configure.srv]], binutils-gdb)]

==== glibc ====

glibc is the only C library for Alpha/Linux. Its library is ''libc.so.6.1'', not ''libc.so.6'', and glibc builds itself with ''-mieee''. Both have Alpha-specific reasons, covered in [[documentation:porting:libc_soname|Why Alpha Has libc.so.6.1]] and [[documentation:porting:floating_point|Floating Point]].

Alpha's ''long double'' is the 128-bit IEEE quadruple format, implemented in software, and its pages are 8 KiB. These and the other ways in which Alpha's Linux ABI differs from x86-64 are described in [[documentation:porting:abi|Linux ABI Differences]].

==== Not available on Alpha ====

The following are missing on Alpha; details and sources are on the [[:status#what_is_missing|Current Status]] page.

  * **LLVM and Clang.** LLVM has had no Alpha back end since 2011, so Clang cannot be used, and the kernel cannot be built with ''LLVM=1''.
  * **Rust**, except through the GCC-based projects rustc_codegen_gcc and gccrs, both still in development. Zig and other LLVM-based compilers are likewise unavailable.
  * **musl.** glibc is the only C library.
  * **The Go toolchain.** ''gccgo'' builds Go code on Alpha.

==== Cross compilers ====

A cross compiler is the usual way to build a kernel for Alpha, and a quick way to check that other software builds. Prebuilt ones are available from several sources:

^ Source ^ Package or file ^ Prefix ^ Notes ^
| Debian and Ubuntu | ''gcc-alpha-linux-gnu'', ''binutils-alpha-linux-gnu'' | ''alpha-linux-gnu-'' | In the main archive. Versioned packages such as ''gcc-15-alpha-linux-gnu'' are also available. [(>[[https://packages.debian.org/search?keywords=gcc-alpha-linux-gnu|gcc-alpha-linux-gnu]], packages.debian.org)] Includes glibc, so it builds user programs as well as kernels |
| Gentoo | ''crossdev --target alpha-unknown-linux-gnu'' | ''alpha-unknown-linux-gnu-'' | Builds binutils, GCC, the kernel headers, and glibc from source |
| kernel.org | ''x86_64-gcc-//version//-nolibc-alpha-linux.tar.xz'' | ''alpha-linux-'' | Arnd Bergmann's prebuilt compilers, [[https://mirrors.edge.kernel.org/pub/tools/crosstool/|mirrors.edge.kernel.org/pub/tools/crosstool]]. Without a C library, so for kernels only |

For example, on Debian:

<code>
apt install gcc-alpha-linux-gnu
alpha-linux-gnu-gcc -O2 -mcpu=ev56 -o hello hello.c
qemu-alpha -L /usr/alpha-linux-gnu ./hello
</code>

The last line runs the result with QEMU's user-mode emulator; see [[documentation:qemu#user-mode_emulation|QEMU]]. Building a kernel with a cross compiler is described on the [[documentation:kernel#cross_compiling|Kernel]] page.

==== Compaq C ====

Compaq C (''ccc'') was the DEC C compiler of Digital UNIX and OpenVMS, built on Digital's GEM optimizing back end and retargeted to Linux. Compaq released it free of charge in December 1999, with a Fortran compiler (''fort''), a C++ compiler (''cxx''), and the CPML and CXML math libraries. [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/axp-list-mbox/1999-December.mbox#L32196|"Compaq C V6.2 for Linux Alpha is available"]], Compaq C/C++ Team, axp-list, 17 Dec 1999)] It was faster than GCC on floating-point code, but by 2003 there was little difference for integer code, [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/comp-os-linux-alpha-mbox/googlegroups-2003-March.mbox#L3402|"Re: GCC vs. ccc"]], Måns Rullgård, comp.os.linux.alpha, 25 Mar 2003)] and it was never used to build a distribution. The packages could not be redistributed, [(>[[https://github.com/alphalinux/mailing-list-archives/blob/main/debian-alpha-mbox/2005-April.mbox#L8850|"Re: HPaq cxx trouble"]], Adam C Powell IV, debian-alpha, 22 Apr 2005)] and the compilers are no longer available.

==== See also ====

  * [[documentation:porting|Porting]], in particular [[documentation:porting:floating_point|Floating Point]] for ''-mieee'' and [[documentation:porting:byte_word_access|Byte and Word Access]] for BWX
  * [[documentation:porting:abi|Linux ABI Differences]], for ''long double'', the page size, and system call conventions
  * [[documentation:amask|Architecture Mask (amask)]] for detecting extensions at runtime
  * [[documentation:instruction_set|Instruction Set]]
  * [[tasks:bugs|Bugs]] for open gcc, glibc and binutils bugs against Alpha

{{tag>documentation toolchain}}