diff options
Diffstat (limited to 'static/freebsd/man7/arch.7')
| -rw-r--r-- | static/freebsd/man7/arch.7 | 563 |
1 files changed, 563 insertions, 0 deletions
diff --git a/static/freebsd/man7/arch.7 b/static/freebsd/man7/arch.7 new file mode 100644 index 00000000..628d3837 --- /dev/null +++ b/static/freebsd/man7/arch.7 @@ -0,0 +1,563 @@ +.\" Copyright (c) 2016-2017 The FreeBSD Foundation. +.\" +.\" This documentation was created by Ed Maste under sponsorship of +.\" The FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd November 27, 2025 +.Dt ARCH 7 +.Os +.Sh NAME +.Nm arch +.Nd Architecture-specific details +.Sh DESCRIPTION +Differences between CPU architectures and platforms supported by +.Fx . +.Ss Introduction +This document is a quick reference of key ABI details of +.Fx +architecture ports. +For full details consult the processor-specific ABI supplement +documentation. +.Pp +If not explicitly mentioned, sizes are in bytes. +The architecture details in this document apply to +.Fx 13.0 +and later, unless otherwise noted. +.Pp +.Fx +uses a flat address space. +Variables of types +.Vt unsigned long , +.Vt ptraddr_t , +and +.Vt size_t +have the same representation. +.Pp +In order to maximize compatibility with future pointer integrity mechanisms, +manipulations of pointers as integers should be performed via +.Vt uintptr_t +or +.Vt intptr_t +and no other types as these types are the only integer types where the +C standard guarantees that a pointer may be cast to it and then cast back +to the original type. +On CHERI systems, +.Vt uintptr_t +and +.Vt intptr_t +are defined as +.Vt __uintcap_t +and +.Vt __intcap_t +which represent capabilities that can be manipulated by integer operations. +Pointers should not be cast to +.Vt long , +.Vt ptrdiff_t , +or +.Vt size_t +if they will later be cast back to a pointer that is expected to be +dereferenceable as they remain bare integer types on all architectures. +.Pp +On some architectures, e.g., +AIM variants of +.Dv powerpc64 , +the kernel uses a separate address space. +On other architectures, kernel and a user mode process share a +single address space. +The kernel is located at the highest addresses. +.Pp +On each architecture, the main user mode thread's stack starts near +the highest user address and grows down. +.Pp +.Fx +architecture support varies by release. +This table shows currently supported CPU architectures along with the first +.Fx +release to support each architecture. +.Bl -column -offset indent "Architecture" "Initial Release" +.It Sy Architecture Ta Sy Initial Release +.It aarch64 Ta 11.0 +.It aarch64c Ta 16.0 (planned) +.It amd64 Ta 5.1 +.It armv7 Ta 12.0 +.It powerpc64 Ta 9.0 +.It powerpc64le Ta 13.0 +.It riscv64 Ta 12.0 +.It riscv64c Ta 16.0 (planned) +.El +.Pp +Discontinued architectures are shown in the following table. +.Bl -column -offset indent "Architecture" "Initial Release" "Final Release" +.It Sy Architecture Ta Sy Initial Release Ta Sy Final Release +.It alpha Ta 3.2 Ta 6.4 +.It arm Ta 6.0 Ta 12.4 +.It armeb Ta 8.0 Ta 11.4 +.It armv6 Ta 10.0 Ta 14.x +.It ia64 Ta 5.0 Ta 10.4 +.It i386 Ta 1.0 Ta 14.x +.It mips Ta 8.0 Ta 13.5 +.It mipsel Ta 9.0 Ta 13.5 +.It mipselhf Ta 12.0 Ta 13.5 +.It mipshf Ta 12.0 Ta 13.5 +.It mipsn32 Ta 9.0 Ta 13.5 +.It mips64 Ta 9.0 Ta 13.5 +.It mips64el Ta 9.0 Ta 13.5 +.It mips64elhf Ta 12.0 Ta 13.5 +.It mips64hf Ta 12.0 Ta 13.5 +.It pc98 Ta 2.2 Ta 11.4 +.It powerpc Ta 6.0 Ta 14.x +.It powerpcspe Ta 12.0 Ta 14.x +.It riscv64sf Ta 12.0 Ta 13.5 +.It sparc64 Ta 5.0 Ta 12.4 +.El +.Ss Type sizes +All +.Fx +architectures use some variant of the ELF (see +.Xr elf 5 ) +.Sy Application Binary Interface +(ABI) for the machine processor. +Supported ABIs can be divided into three main groups: +.Bl -tag -width "Dv L64PC128" +.It Dv ILP32 +.Vt int , +.Vt intptr_t , +.Vt long , +and +.Vt void * +types machine representations all have 4-byte size. +.It Dv LP64 +.Vt int +type machine representation uses 4 bytes, +while +.Vt intptr_t , +.Vt long , +and +.Vt void * +are 8 bytes. +.It Dv L64PC128 +.Vt int +type machine representation uses 4 bytes. +.Vt long +type machine representation uses 8 bytes. +.Vt intptr_t +and +.Vt void * +are 16 byte capabilities. +.El +.Pp +Some machines support more than one +.Fx +ABI. +Typically these are 64-bit machines, where the +.Dq native +.Dv LP64 +execution environment is accompanied by the +.Dq legacy +.Dv ILP32 +environment, which was the historical 32-bit predecessor for 64-bit evolution. +Examples are: +.Bl -column -offset indent "powerpc64" "ILP32 counterpart" +.It Sy LP64 Ta Sy ILP32 counterpart +.It Dv amd64 Ta Dv i386 +.It Dv powerpc64 Ta Dv powerpc +.It Dv aarch64 Ta Dv armv7 +.El +.Pp +.Dv aarch64 +will support execution of +.Dv armv7 +binaries if the CPU implements +.Dv AArch32 +execution state. +Binaries targeting +.Dv armv6 +and earlier are no longer supported by +.Fx . +.Pp +Architectures with 128-bit capabilities support both a +.Dq native +.Dv L64PC128 +execution environment and a +.Dv LP64 +environment: +.Bl -column -offset indent "aarch64c" "LP64 counterpart" +.It Sy L64PC128 Ta Sy LP64 counterpart +.It Dv aarch64c Ta Dv aarch64 +.It Dv riscv64c Ta Dv riscv64 +.El +.Pp +On all supported architectures: +.Bl -column -offset indent "long long" "Size" +.It Sy Type Ta Sy Size +.It short Ta 2 +.It int Ta 4 +.It long long Ta 8 +.It float Ta 4 +.It double Ta 8 +.El +.Pp +Integers are represented in two's complement. +Alignment of integer and pointer types is natural, that is, +the address of the variable must be congruent to zero modulo the type size. +The sole exception is that +.Dv i386 +requires only 4-byte alignment for 64-bit integers. +.Pp +Machine-dependent type sizes: +.Bl -column -offset indent "Architecture" "long" "void *" "long double" "time_t" +.It Sy Architecture Ta Sy long Ta Sy void * Ta Sy long double Ta Sy time_t +.It aarch64 Ta 8 Ta 8 Ta 16 Ta 8 +.It aarch64c Ta 8 Ta 16 Ta 16 Ta 8 +.It amd64 Ta 8 Ta 8 Ta 16 Ta 8 +.It armv7 Ta 4 Ta 4 Ta 8 Ta 8 +.It i386 Ta 4 Ta 4 Ta 12 Ta 4 +.It powerpc Ta 4 Ta 4 Ta 8 Ta 8 +.It powerpcspe Ta 4 Ta 4 Ta 8 Ta 8 +.It powerpc64 Ta 8 Ta 8 Ta 8 Ta 8 +.It powerpc64le Ta 8 Ta 8 Ta 8 Ta 8 +.It riscv64 Ta 8 Ta 8 Ta 16 Ta 8 +.It riscv64c Ta 8 Ta 16 Ta 16 Ta 8 +.El +.Pp +.Sy time_t +is 8 bytes on all supported architectures except i386. +.Ss Endianness and Char Signedness +.Bl -column -offset indent "Architecture" "Endianness" "char Signedness" +.It Sy Architecture Ta Sy Endianness Ta Sy char Signedness +.It aarch64 Ta little Ta unsigned +.It aarch64c Ta little Ta unsigned +.It amd64 Ta little Ta signed +.It armv7 Ta little Ta unsigned +.It i386 Ta little Ta signed +.It powerpc Ta big Ta unsigned +.It powerpcspe Ta big Ta unsigned +.It powerpc64 Ta big Ta unsigned +.It powerpc64le Ta little Ta unsigned +.It riscv64 Ta little Ta signed +.It riscv64c Ta little Ta signed +.El +.Ss Page Size +.Bl -column -offset indent "Architecture" "Page Sizes" +.It Sy Architecture Ta Sy Page Sizes +.It aarch64 Ta 4K, 64K, 2M, 1G +.It aarch64c Ta 4K, 64K, 2M, 1G +.It amd64 Ta 4K, 2M, 1G +.It armv7 Ta 4K, 1M +.It i386 Ta 4K, 2M (PAE), 4M +.It powerpc Ta 4K +.It powerpcspe Ta 4K +.It powerpc64 Ta 4K +.It powerpc64le Ta 4K +.It riscv64 Ta 4K, 2M, 1G +.It riscv64c Ta 4K, 2M, 1G +.El +.Ss User Address Space Layout +.Bl -column -offset indent "riscv64 (Sv48)" "0x0001000000000000" "NNNU" +.It Sy Architecture Ta Sy Maximum Address Ta Sy Address Space Size +.It aarch64 Ta 0x0001000000000000 Ta 256TiB +.It aarch64c Ta 0x0001000000000000 Ta 256TiB +.It amd64 (LA48) Ta 0x0000800000000000 Ta 128TiB +.It amd64 (LA57) Ta 0x0100000000000000 Ta 64PiB +.It armv7 Ta 0xbfc00000 Ta 3GiB +.It i386 Ta 0xffc00000 Ta 4GiB +.It powerpc Ta 0xfffff000 Ta 4GiB +.It powerpcspe Ta 0x7ffff000 Ta 2GiB +.It powerpc64 Ta 0x000fffffc0000000 Ta 4PiB +.It powerpc64le Ta 0x000fffffc0000000 Ta 4PiB +.It riscv64 (Sv39) Ta 0x0000004000000000 Ta 256GiB +.It riscv64c (Sv39) Ta 0x0000004000000000 Ta 256GiB +.It riscv64 (Sv48) Ta 0x0000800000000000 Ta 128TiB +.It riscv64c (Sv48) Ta 0x0000800000000000 Ta 128TiB +.El +.Pp +The layout of a process' address space can be queried via the +.Dv KERN_PROC_VM_LAYOUT +.Xr sysctl 3 +MIB. +.Pp +Historically, amd64 CPUs were limited to a 48-bit virtual address space. +Newer CPUs support 5-level page tables, which extend the significant bits of +addresses to 57 bits (LA57 mode). +The address space layout is determined by the CPU's support for LA57. +Setting the +.Sy vm.pmap.la57 +tunable to 0 forces the system into 4-level paging mode, even on hardware that +supports 5-level paging. +In this mode, all processes get a 48-bit address space. +The +.Sy vm.pmap.prefer_la48_uva +tunable determines whether processes running on a LA57 system are limited to +a 48-bit address space by default. +Some applications make use of unused upper bits in pointer values to store +information, and thus implicitly assume they are running in LA48 mode. +To avoid breaking compatibility, all processes run in LA48 mode by default. +The +.Xr elfctl 1 +utility can be used to request LA48 or LA57 mode for specific executables. +Similarly, +.Xr proccontrol 1 +can be used to configure the address space layout when executing a process. +.Pp +The RISC-V specification permits 3-level (Sv39), 4-level (Sv48), and +5-level (Sv57) page tables. +Hardware is only required to implement Sv39; implementations which support +Sv48 must also support Sv39, and implementations which support Sv57 must also +support Sv48. +The +.Sy vm.pmap.mode +tunable can be used to select the layout. +.Fx +currently supports Sv39 and Sv48 and defaults to using Sv39. +.Ss Floating Point +.Bl -column -offset indent "Architecture" "float, double" "long double" +.It Sy Architecture Ta Sy float, double Ta Sy long double +.It aarch64 Ta hard Ta soft, quad precision +.It aarch64c Ta hard Ta soft, quad precision +.It amd64 Ta hard Ta hard, 80 bit +.It armv7 Ta hard Ta hard, double precision +.It i386 Ta hard Ta hard, 80 bit +.It powerpc Ta hard Ta hard, double precision +.It powerpcspe Ta hard Ta hard, double precision +.It powerpc64 Ta hard Ta hard, double precision +.It powerpc64le Ta hard Ta hard, double precision +.It riscv64 Ta hard Ta hard, quad precision +.It riscv64c Ta hard Ta hard, quad precision +.El +.Ss Default Tool Chain +.Fx +uses +.Xr clang 1 +as the default compiler on all supported CPU architectures, +LLVM's +.Xr ld.lld 1 +as the default linker, and +LLVM binary utilities such as +.Xr objcopy 1 +and +.Xr readelf 1 . +.Ss MACHINE_ARCH vs MACHINE_CPUARCH vs MACHINE +.Dv MACHINE_CPUARCH +should be preferred in Makefiles when the generic +architecture is being tested. +.Dv MACHINE_ARCH +should be preferred when there is something specific to a particular type of +architecture where there is a choice of many, or could be a choice of many. +Use +.Dv MACHINE +when referring to the kernel, interfaces dependent on a specific type of kernel +or similar things like boot sequences. +.Bl -column -offset indent "Dv MACHINE" "Dv MACHINE_CPUARCH" "Dv MACHINE_ARCH" +.It Dv MACHINE Ta Dv MACHINE_CPUARCH Ta Dv MACHINE_ARCH +.It arm64 Ta aarch64 Ta aarch64, aarch64c +.It amd64 Ta amd64 Ta amd64 +.It arm Ta arm Ta armv7 +.It i386 Ta i386 Ta i386 +.It powerpc Ta powerpc Ta powerpc, powerpcspe, powerpc64, powerpc64le +.It riscv Ta riscv Ta riscv64, riscv64c +.El +.Ss Predefined Macros +The compiler provides a number of predefined macros. +Some of these provide architecture-specific details and are explained below. +Other macros, including those required by the language standard, are not +included here. +.Pp +The full set of predefined macros can be obtained with this command: +.Bd -literal -offset indent +cc -x c -dM -E /dev/null +.Ed +.Pp +Common type size and endianness macros: +.Bl -column -offset indent "__SIZEOF_POINTER__" "Meaning" +.It Sy Macro Ta Sy Meaning +.It Dv __SIZEOF_LONG__ Ta size in bytes of long +.It Dv __SIZEOF_POINTER__ Ta size in bytes of intptr_t and pointers +.It Dv __SIZEOF_SIZE_T__ Ta size in bytes of size_t +.It Dv __LP64__ Ta 64-bit (8-byte) long and pointer, 32-bit (4-byte) int +.It Dv __ILP32__ Ta 32-bit (4-byte) int, long and pointer +.It Dv __CHERI__ Ta 128-bit (16-byte) capability pointer, 64-bit (8-byte) long +.It Dv BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN . +.El +.Pp +Because systems were historically either +.Dv __ILP32__ +or +.Dv __LP64__ +it has been common for programmers to test only one and assume the other +one in an else branch. +With the arrival of CHERI architectures, this is no longer the case. +.Dv __SIZEOF_*__ +macros should be used instead. +New uses of +.Dv __ILP32__ +and +.Dv __LP64__ +should be avoided. +Compilers for CHERI targets do not define +.Dv __LP64__ +as their pointers are 128-bit capabilities. +.Pp +Architecture-specific macros: +.Bl -column -offset indent "Architecture" "Predefined macros" +.It Sy Architecture Ta Sy Predefined macros +.It aarch64 Ta Dv __aarch64__ +.It aarch64c Ta Dv __aarch64__ , Dv __CHERI__ +.It amd64 Ta Dv __amd64__ , Dv __x86_64__ +.It armv7 Ta Dv __arm__ , Dv __ARM_ARCH >= 7 +.It i386 Ta Dv __i386__ +.It powerpc Ta Dv __powerpc__ +.It powerpcspe Ta Dv __powerpc__ , Dv __SPE__ +.It powerpc64 Ta Dv __powerpc__ , Dv __powerpc64__ +.It powerpc64le Ta Dv __powerpc__ , Dv __powerpc64__ +.It riscv64 Ta Dv __riscv , Dv __riscv_xlen == 64 +.It riscv64c Ta Dv __riscv , Dv __riscv_xlen == 64 , Dv __CHERI__ +.El +.Pp +Compilers may define additional variants of architecture-specific macros. +The macros above are preferred for use in +.Fx . +.Ss Important Xr make 1 variables +Most of the externally settable variables are defined in the +.Xr build 7 +man page. +These variables are not otherwise documented and are used extensively +in the build system. +.Bl -tag -width "MACHINE_CPUARCH" +.It Dv MACHINE +Represents the hardware platform. +This is the same as the native platform's +.Xr uname 1 +.Fl m +output. +It defines both the userland / kernel interface, as well as the +bootloader / kernel interface. +It should only be used in these contexts. +Each CPU architecture may have multiple hardware platforms it supports +where +.Dv MACHINE +differs among them. +It is used to collect together all the files from +.Xr config 8 +to build the kernel. +It is often the same as +.Dv MACHINE_ARCH +just as one CPU architecture can be implemented by many different +hardware platforms, one hardware platform may support multiple CPU +architecture family members, though with different binaries. +For example, +.Dv MACHINE +of i386 supported the IBM-AT hardware platform while the +.Dv MACHINE +of pc98 supported the Japanese company NEC's PC-9801 and PC-9821 +hardware platforms. +Both of these hardware platforms supported only the +.Dv MACHINE_ARCH +of i386 where they shared a common ABI, except for certain kernel / +userland interfaces relating to underlying hardware platform +differences in bus architecture, device enumeration and boot interface. +Generally, +.Dv MACHINE +should only be used in src/sys and src/stand or in system imagers or +installers. +.It Dv MACHINE_ARCH +Represents the CPU processor architecture. +This is the same as the native platforms +.Xr uname 1 +.Fl p +output. +It defines the CPU instruction family supported. +It may also encode a variation in the byte ordering of multi-byte +integers (endian). +It may also encode a variation in the size of the integer or pointer. +It may also encode a ISA revision. +It may also encode hard versus soft floating point ABI and usage. +It may also encode a variant ABI when the other factors do not +uniquely define the ABI. +It, along with +.Dv MACHINE , +defines the ABI used by the system. +Generally, the plain CPU name specifies the most common (or at least +first) variant of the CPU. +This is why powerpc and powerpc64 imply 'big endian' while armv7 and aarch64 +imply little endian. +If we ever were to support the so-called x32 ABI (using 32-bit +pointers on the amd64 architecture), it would most likely be encoded +as amd64-x32. +It is unfortunate that amd64 specifies the 64-bit evolution of the x86 platform +(it matches the 'first rule') as almost everybody else uses x86_64. +The +.Fx +port was so early, it predated processor name standardization after Intel joined +the market. +At the time, each OS selected its own conventions. +Backwards compatibility means it is not easy to change to the consensus name. +.It Dv MACHINE_CPUARCH +Represents the source location for a given +.Dv MACHINE_ARCH . +It is generally the common prefix for all the MACHINE_ARCH that +share the same implementation, though 'riscv' breaks this rule. +While amd64 and i386 are closely related, MACHINE_CPUARCH is not x86 +for them. +The +.Fx +source base supports amd64 and i386 with two +distinct source bases living in subdirectories named amd64 and i386 +(though behind the scenes there's some sharing that fits into this +framework). +.It Dv CPUTYPE +Sets the flavor of +.Dv MACHINE_ARCH +to build. +It is used to optimize the build for a specific CPU / core that the +binaries run on. +Generally, this does not change the ABI, though it can be a fine line +between optimization for specific cases. +.It Dv TARGET +Used to set +.Dv MACHINE +in the top level Makefile for cross building. +Unused outside of that scope. +It is not passed down to the rest of the build. +Makefiles outside of the top level should not use it at all (though +some have their own private copy for historical reasons). +.It Dv TARGET_ARCH +Used to set +.Dv MACHINE_ARCH +by the top level Makefile for cross building. +Like +.Dv TARGET , +it is unused outside of that scope. +.El +.Sh SEE ALSO +.Xr elfctl 1 , +.Xr proccontrol 1 , +.Xr sysctl 3 , +.Xr src.conf 5 , +.Xr build 7 , +.Xr simd 7 +.Sh HISTORY +An +.Nm +manual page appeared in +.Fx 11.1 . |