1.\" Copyright (c) 2016-2017 The FreeBSD Foundation. 2.\" 3.\" This documentation was created by Ed Maste under sponsorship of 4.\" The FreeBSD Foundation. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd April 12, 2025 28.Dt ARCH 7 29.Os 30.Sh NAME 31.Nm arch 32.Nd Architecture-specific details 33.Sh DESCRIPTION 34Differences between CPU architectures and platforms supported by 35.Fx . 36.Ss Introduction 37This document is a quick reference of key ABI details of 38.Fx 39architecture ports. 40For full details consult the processor-specific ABI supplement 41documentation. 42.Pp 43If not explicitly mentioned, sizes are in bytes. 44The architecture details in this document apply to 45.Fx 13.0 46and later, unless otherwise noted. 47.Pp 48.Fx 49uses a flat address space. 50Variables of types 51.Vt unsigned long , 52.Vt uintptr_t , 53and 54.Vt size_t 55and pointers all have the same representation. 56.Pp 57In order to maximize compatibility with future pointer integrity mechanisms, 58manipulations of pointers as integers should be performed via 59.Vt uintptr_t 60or 61.Vt intptr_t 62and no other types. 63In particular, 64.Vt long 65and 66.Vt ptrdiff_t 67should be avoided. 68.Pp 69On some architectures, e.g., 70.Dv powerpc 71and AIM variants of 72.Dv powerpc64 , 73the kernel uses a separate address space. 74On other architectures, kernel and a user mode process share a 75single address space. 76The kernel is located at the highest addresses. 77.Pp 78On each architecture, the main user mode thread's stack starts near 79the highest user address and grows down. 80.Pp 81.Fx 82architecture support varies by release. 83This table shows currently supported CPU architectures along with the first 84.Fx 85release to support each architecture. 86.Bl -column -offset indent "Architecture" "Initial Release" 87.It Sy Architecture Ta Sy Initial Release 88.It aarch64 Ta 11.0 89.It amd64 Ta 5.1 90.It armv7 Ta 12.0 91.It i386 Ta 1.0 92.It powerpc Ta 6.0 93.It powerpcspe Ta 12.0 94.It powerpc64 Ta 9.0 95.It powerpc64le Ta 13.0 96.It riscv64 Ta 12.0 97.El 98.Pp 99Discontinued architectures are shown in the following table. 100.Bl -column -offset indent "Architecture" "Initial Release" "Final Release" 101.It Sy Architecture Ta Sy Initial Release Ta Sy Final Release 102.It alpha Ta 3.2 Ta 6.4 103.It arm Ta 6.0 Ta 12.4 104.It armeb Ta 8.0 Ta 11.4 105.It armv6 Ta 10.0 Ta 14.x 106.It ia64 Ta 5.0 Ta 10.4 107.It mips Ta 8.0 Ta 13.5 108.It mipsel Ta 9.0 Ta 13.5 109.It mipselhf Ta 12.0 Ta 13.5 110.It mipshf Ta 12.0 Ta 13.5 111.It mipsn32 Ta 9.0 Ta 13.5 112.It mips64 Ta 9.0 Ta 13.5 113.It mips64el Ta 9.0 Ta 13.5 114.It mips64elhf Ta 12.0 Ta 13.5 115.It mips64hf Ta 12.0 Ta 13.5 116.It pc98 Ta 2.2 Ta 11.4 117.It riscv64sf Ta 12.0 Ta 13.5 118.It sparc64 Ta 5.0 Ta 12.4 119.El 120.Ss Type sizes 121All 122.Fx 123architectures use some variant of the ELF (see 124.Xr elf 5 ) 125.Sy Application Binary Interface 126(ABI) for the machine processor. 127All supported ABIs can be divided into two groups: 128.Bl -tag -width "Dv ILP32" 129.It Dv ILP32 130.Vt int , 131.Vt long , 132.Vt void * 133types machine representations all have 4-byte size. 134.It Dv LP64 135.Vt int 136type machine representation uses 4 bytes, 137while 138.Vt long 139and 140.Vt void * 141are 8 bytes. 142.El 143.Pp 144Some machines support more than one 145.Fx 146ABI. 147Typically these are 64-bit machines, where the 148.Dq native 149.Dv LP64 150execution environment is accompanied by the 151.Dq legacy 152.Dv ILP32 153environment, which was the historical 32-bit predecessor for 64-bit evolution. 154Examples are: 155.Bl -column -offset indent "powerpc64" "ILP32 counterpart" 156.It Sy LP64 Ta Sy ILP32 counterpart 157.It Dv amd64 Ta Dv i386 158.It Dv powerpc64 Ta Dv powerpc 159.It Dv aarch64 Ta Dv armv7 160.El 161.Pp 162.Dv aarch64 163will support execution of 164.Dv armv7 165binaries if the CPU implements 166.Dv AArch32 167execution state, however older arm binaries are not supported by 168.Fx . 169.Pp 170On all supported architectures: 171.Bl -column -offset indent "long long" "Size" 172.It Sy Type Ta Sy Size 173.It short Ta 2 174.It int Ta 4 175.It long Ta sizeof(void*) 176.It long long Ta 8 177.It float Ta 4 178.It double Ta 8 179.El 180.Pp 181Integers are represented in two's complement. 182Alignment of integer and pointer types is natural, that is, 183the address of the variable must be congruent to zero modulo the type size. 184Most ILP32 ABIs, except 185.Dv arm , 186require only 4-byte alignment for 64-bit integers. 187.Pp 188Machine-dependent type sizes: 189.Bl -column -offset indent "Architecture" "void *" "long double" "time_t" 190.It Sy Architecture Ta Sy void * Ta Sy long double Ta Sy time_t 191.It aarch64 Ta 8 Ta 16 Ta 8 192.It amd64 Ta 8 Ta 16 Ta 8 193.It armv7 Ta 4 Ta 8 Ta 8 194.It i386 Ta 4 Ta 12 Ta 4 195.It powerpc Ta 4 Ta 8 Ta 8 196.It powerpcspe Ta 4 Ta 8 Ta 8 197.It powerpc64 Ta 8 Ta 8 Ta 8 198.It powerpc64le Ta 8 Ta 8 Ta 8 199.It riscv64 Ta 8 Ta 16 Ta 8 200.El 201.Pp 202.Sy time_t 203is 8 bytes on all supported architectures except i386. 204.Ss Endianness and Char Signedness 205.Bl -column -offset indent "Architecture" "Endianness" "char Signedness" 206.It Sy Architecture Ta Sy Endianness Ta Sy char Signedness 207.It aarch64 Ta little Ta unsigned 208.It amd64 Ta little Ta signed 209.It armv7 Ta little Ta unsigned 210.It i386 Ta little Ta signed 211.It powerpc Ta big Ta unsigned 212.It powerpcspe Ta big Ta unsigned 213.It powerpc64 Ta big Ta unsigned 214.It powerpc64le Ta little Ta unsigned 215.It riscv64 Ta little Ta signed 216.El 217.Ss Page Size 218.Bl -column -offset indent "Architecture" "Page Sizes" 219.It Sy Architecture Ta Sy Page Sizes 220.It aarch64 Ta 4K, 64K, 2M, 1G 221.It amd64 Ta 4K, 2M, 1G 222.It armv7 Ta 4K, 1M 223.It i386 Ta 4K, 2M (PAE), 4M 224.It powerpc Ta 4K 225.It powerpcspe Ta 4K 226.It powerpc64 Ta 4K 227.It powerpc64le Ta 4K 228.It riscv64 Ta 4K, 2M, 1G 229.El 230.Ss User Address Space Layout 231.Bl -column -offset indent "riscv64 (Sv48)" "0x0001000000000000" "NNNU" 232.It Sy Architecture Ta Sy Maximum Address Ta Sy Address Space Size 233.It aarch64 Ta 0x0001000000000000 Ta 256TiB 234.It amd64 (LA48) Ta 0x0000800000000000 Ta 128TiB 235.It amd64 (LA57) Ta 0x0100000000000000 Ta 64PiB 236.It armv7 Ta 0xbfc00000 Ta 3GiB 237.It i386 Ta 0xffc00000 Ta 4GiB 238.It powerpc Ta 0xfffff000 Ta 4GiB 239.It powerpcspe Ta 0x7ffff000 Ta 2GiB 240.It powerpc64 Ta 0x000fffffc0000000 Ta 4PiB 241.It powerpc64le Ta 0x000fffffc0000000 Ta 4PiB 242.It riscv64 (Sv39) Ta 0x0000004000000000 Ta 256GiB 243.It riscv64 (Sv48) Ta 0x0000800000000000 Ta 128TiB 244.El 245.Pp 246The layout of a process' address space can be queried via the 247.Dv KERN_PROC_VM_LAYOUT 248.Xr sysctl 3 249MIB. 250.Pp 251Historically, amd64 CPUs were limited to a 48-bit virtual address space. 252Newer CPUs support 5-level page tables, which extend the significant bits of 253addresses to 57 bits (LA57 mode). 254The address space layout is determined by the CPU's support for LA57. 255Setting the 256.Sy vm.pmap.la57 257tunable to 0 forces the system into 4-level paging mode, even on hardware that 258supports 5-level paging. 259In this mode, all processes get a 48-bit address space. 260The 261.Sy vm.pmap.prefer_la48_uva 262tunable determines whether processes running on a LA57 system are limited to 263a 48-bit address space by default. 264Some applications make use of unused upper bits in pointer values to store 265information, and thus implicitly assume they are running in LA48 mode. 266To avoid breaking compatibility, all processes run in LA48 mode by default. 267The 268.Xr elfctl 1 269utility can be used to request LA48 or LA57 mode for specific executables. 270Similarly, 271.Xr proccontrol 1 272can be used to configure the address space layout when executing a process. 273.Pp 274The RISC-V specification permits 3-level (Sv39), 4-level (Sv48), and 2755-level (Sv57) page tables. 276Hardware is only required to implement Sv39; implementations which support 277Sv48 must also support Sv39, and implementations which support Sv57 must also 278support Sv48. 279The 280.Sy vm.pmap.mode 281tunable can be used to select the layout. 282.Fx 283currently supports Sv39 and Sv48 and defaults to using Sv39. 284.Ss Floating Point 285.Bl -column -offset indent "Architecture" "float, double" "long double" 286.It Sy Architecture Ta Sy float, double Ta Sy long double 287.It aarch64 Ta hard Ta soft, quad precision 288.It amd64 Ta hard Ta hard, 80 bit 289.It armv7 Ta hard Ta hard, double precision 290.It i386 Ta hard Ta hard, 80 bit 291.It powerpc Ta hard Ta hard, double precision 292.It powerpcspe Ta hard Ta hard, double precision 293.It powerpc64 Ta hard Ta hard, double precision 294.It powerpc64le Ta hard Ta hard, double precision 295.It riscv64 Ta hard Ta hard, quad precision 296.El 297.Ss Default Tool Chain 298.Fx 299uses 300.Xr clang 1 301as the default compiler on all supported CPU architectures, 302LLVM's 303.Xr ld.lld 1 304as the default linker, and 305LLVM binary utilities such as 306.Xr objcopy 1 307and 308.Xr readelf 1 . 309.Ss MACHINE_ARCH vs MACHINE_CPUARCH vs MACHINE 310.Dv MACHINE_CPUARCH 311should be preferred in Makefiles when the generic 312architecture is being tested. 313.Dv MACHINE_ARCH 314should be preferred when there is something specific to a particular type of 315architecture where there is a choice of many, or could be a choice of many. 316Use 317.Dv MACHINE 318when referring to the kernel, interfaces dependent on a specific type of kernel 319or similar things like boot sequences. 320.Bl -column -offset indent "Dv MACHINE" "Dv MACHINE_CPUARCH" "Dv MACHINE_ARCH" 321.It Dv MACHINE Ta Dv MACHINE_CPUARCH Ta Dv MACHINE_ARCH 322.It arm64 Ta aarch64 Ta aarch64 323.It amd64 Ta amd64 Ta amd64 324.It arm Ta arm Ta armv7 325.It i386 Ta i386 Ta i386 326.It powerpc Ta powerpc Ta powerpc, powerpcspe, powerpc64, powerpc64le 327.It riscv Ta riscv Ta riscv64 328.El 329.Ss Predefined Macros 330The compiler provides a number of predefined macros. 331Some of these provide architecture-specific details and are explained below. 332Other macros, including those required by the language standard, are not 333included here. 334.Pp 335The full set of predefined macros can be obtained with this command: 336.Bd -literal -offset indent 337cc -x c -dM -E /dev/null 338.Ed 339.Pp 340Common type size and endianness macros: 341.Bl -column -offset indent "BYTE_ORDER" "Meaning" 342.It Sy Macro Ta Sy Meaning 343.It Dv __LP64__ Ta 64-bit (8-byte) long and pointer, 32-bit (4-byte) int 344.It Dv __ILP32__ Ta 32-bit (4-byte) int, long and pointer 345.It Dv BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN . 346.Dv PDP11_ENDIAN 347is not used on 348.Fx . 349.El 350.Pp 351Architecture-specific macros: 352.Bl -column -offset indent "Architecture" "Predefined macros" 353.It Sy Architecture Ta Sy Predefined macros 354.It aarch64 Ta Dv __aarch64__ 355.It amd64 Ta Dv __amd64__ , Dv __x86_64__ 356.It armv7 Ta Dv __arm__ , Dv __ARM_ARCH >= 7 357.It i386 Ta Dv __i386__ 358.It powerpc Ta Dv __powerpc__ 359.It powerpcspe Ta Dv __powerpc__ , Dv __SPE__ 360.It powerpc64 Ta Dv __powerpc__ , Dv __powerpc64__ 361.It powerpc64le Ta Dv __powerpc__ , Dv __powerpc64__ 362.It riscv64 Ta Dv __riscv , Dv __riscv_xlen == 64 363.El 364.Pp 365Compilers may define additional variants of architecture-specific macros. 366The macros above are preferred for use in 367.Fx . 368.Ss Important Xr make 1 variables 369Most of the externally settable variables are defined in the 370.Xr build 7 371man page. 372These variables are not otherwise documented and are used extensively 373in the build system. 374.Bl -tag -width "MACHINE_CPUARCH" 375.It Dv MACHINE 376Represents the hardware platform. 377This is the same as the native platform's 378.Xr uname 1 379.Fl m 380output. 381It defines both the userland / kernel interface, as well as the 382bootloader / kernel interface. 383It should only be used in these contexts. 384Each CPU architecture may have multiple hardware platforms it supports 385where 386.Dv MACHINE 387differs among them. 388It is used to collect together all the files from 389.Xr config 8 390to build the kernel. 391It is often the same as 392.Dv MACHINE_ARCH 393just as one CPU architecture can be implemented by many different 394hardware platforms, one hardware platform may support multiple CPU 395architecture family members, though with different binaries. 396For example, 397.Dv MACHINE 398of i386 supported the IBM-AT hardware platform while the 399.Dv MACHINE 400of pc98 supported the Japanese company NEC's PC-9801 and PC-9821 401hardware platforms. 402Both of these hardware platforms supported only the 403.Dv MACHINE_ARCH 404of i386 where they shared a common ABI, except for certain kernel / 405userland interfaces relating to underlying hardware platform 406differences in bus architecture, device enumeration and boot interface. 407Generally, 408.Dv MACHINE 409should only be used in src/sys and src/stand or in system imagers or 410installers. 411.It Dv MACHINE_ARCH 412Represents the CPU processor architecture. 413This is the same as the native platforms 414.Xr uname 1 415.Fl p 416output. 417It defines the CPU instruction family supported. 418It may also encode a variation in the byte ordering of multi-byte 419integers (endian). 420It may also encode a variation in the size of the integer or pointer. 421It may also encode a ISA revision. 422It may also encode hard versus soft floating point ABI and usage. 423It may also encode a variant ABI when the other factors do not 424uniquely define the ABI. 425It, along with 426.Dv MACHINE , 427defines the ABI used by the system. 428Generally, the plain CPU name specifies the most common (or at least 429first) variant of the CPU. 430This is why powerpc and powerpc64 imply 'big endian' while armv7 and aarch64 431imply little endian. 432If we ever were to support the so-called x32 ABI (using 32-bit 433pointers on the amd64 architecture), it would most likely be encoded 434as amd64-x32. 435It is unfortunate that amd64 specifies the 64-bit evolution of the x86 platform 436(it matches the 'first rule') as almost everybody else uses x86_64. 437The 438.Fx 439port was so early, it predated processor name standardization after Intel joined 440the market. 441At the time, each OS selected its own conventions. 442Backwards compatibility means it is not easy to change to the consensus name. 443.It Dv MACHINE_CPUARCH 444Represents the source location for a given 445.Dv MACHINE_ARCH . 446It is generally the common prefix for all the MACHINE_ARCH that 447share the same implementation, though 'riscv' breaks this rule. 448While amd64 and i386 are closely related, MACHINE_CPUARCH is not x86 449for them. 450The 451.Fx 452source base supports amd64 and i386 with two 453distinct source bases living in subdirectories named amd64 and i386 454(though behind the scenes there's some sharing that fits into this 455framework). 456.It Dv CPUTYPE 457Sets the flavor of 458.Dv MACHINE_ARCH 459to build. 460It is used to optimize the build for a specific CPU / core that the 461binaries run on. 462Generally, this does not change the ABI, though it can be a fine line 463between optimization for specific cases. 464.It Dv TARGET 465Used to set 466.Dv MACHINE 467in the top level Makefile for cross building. 468Unused outside of that scope. 469It is not passed down to the rest of the build. 470Makefiles outside of the top level should not use it at all (though 471some have their own private copy for historical reasons). 472.It Dv TARGET_ARCH 473Used to set 474.Dv MACHINE_ARCH 475by the top level Makefile for cross building. 476Like 477.Dv TARGET , 478it is unused outside of that scope. 479.El 480.Sh SEE ALSO 481.Xr elfctl 1 , 482.Xr proccontrol 1 , 483.Xr sysctl 3 , 484.Xr src.conf 5 , 485.Xr build 7 , 486.Xr simd 7 487.Sh HISTORY 488An 489.Nm 490manual page appeared in 491.Fx 11.1 . 492