456 lines
15 KiB
Groff
456 lines
15 KiB
Groff
.\" Copyright (c) 2016-2017 The FreeBSD Foundation. All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 15, 2017
|
|
.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 10.0
|
|
and later, unless otherwise noted.
|
|
.Pp
|
|
.Fx
|
|
uses a flat address space.
|
|
Variables of types
|
|
.Vt unsigned long ,
|
|
.Vt uintptr_t ,
|
|
and
|
|
.Vt size_t
|
|
and pointers all 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.
|
|
In particular,
|
|
.Vt long
|
|
and
|
|
.Vt ptrdiff_t
|
|
should be avoided.
|
|
.Pp
|
|
On some architectures, e.g.,
|
|
.Dv sparc64 ,
|
|
.Dv powerpc
|
|
and 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 the first
|
|
.Fx
|
|
release to support each architecture, and, for discontinued
|
|
architectures, the final release.
|
|
.Pp
|
|
.Bl -column -offset indent "Sy Architecture" "Sy Initial Release" "Sy Final Release"
|
|
.It Sy Architecture Ta Sy Initial Release Ta Sy Final Release
|
|
.It alpha Ta 3.2 Ta 6.4
|
|
.It amd64 Ta 5.1
|
|
.It arm Ta 6.0
|
|
.It armeb Ta 8.0
|
|
.It armv6 Ta 10.0
|
|
.It arm64 Ta 11.0
|
|
.It ia64 Ta 5.0 Ta 10.x
|
|
.It i386 Ta 1.0
|
|
.It mips Ta 8.0
|
|
.It mipsel Ta 9.0
|
|
.It mipselhf Ta 12.0
|
|
.It mipshf Ta 12.0
|
|
.It mipsn32 Ta 9.0
|
|
.It mips64 Ta 9.0
|
|
.It mips64el Ta 9.0
|
|
.It mips64elhf Ta 12.0
|
|
.It mips64hf Ta 12.0
|
|
.It pc98 Ta 2.2 Ta 11.x
|
|
.It powerpc Ta 6.0
|
|
.It powerpcspe Ta 12.0
|
|
.It powerpc64 Ta 6.0
|
|
.It riscv64 Ta 12.0
|
|
.It riscv64sf Ta 12.0
|
|
.It sparc64 Ta 5.0
|
|
.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.
|
|
All supported ABIs can be divided into two groups:
|
|
.Bl -tag -width "Dv ILP32"
|
|
.It Dv ILP32
|
|
.Vt int ,
|
|
.Vt long ,
|
|
.Vt void *
|
|
types machine representations all have 4-byte size.
|
|
.It Dv LP64
|
|
.Vt int
|
|
type machine representation uses 4 bytes,
|
|
while
|
|
.Vt long
|
|
and
|
|
.Vt void *
|
|
are 8 bytes.
|
|
.El
|
|
Compilers define the
|
|
.Dv _LP64
|
|
symbol when compiling for an
|
|
.Dv LP64
|
|
ABI.
|
|
.Pp
|
|
Some machines support more that 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 historical 32-bit predecessor for 64-bit evolution.
|
|
Examples are:
|
|
.Bl -column -offset indent "Dv powerpc64" "Sy ILP32 counterpart"
|
|
.It Sy LP64 Ta Sy ILP32 counterpart
|
|
.It Dv amd64 Ta Dv i386
|
|
.It Dv powerpc64 Ta Dv powerpc
|
|
.It Dv mips64* Ta Dv mips*
|
|
.El
|
|
.Dv arm64
|
|
currently does not support execution of
|
|
.Dv armv6
|
|
binaries, even if the CPU implements
|
|
.Dv AArch32
|
|
execution state.
|
|
.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 Ta sizeof(void*)
|
|
.It long long Ta 8
|
|
.It float Ta 4
|
|
.It double Ta 8
|
|
.El
|
|
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.
|
|
Most ILP32 ABIs, except
|
|
.Dv arm ,
|
|
require only 4-byte alignment for 64-bit integers.
|
|
.Pp
|
|
Machine-dependent type sizes:
|
|
.Bl -column -offset indent "Sy Architecture" "Sy void *" "Sy long double" "Sy time_t"
|
|
.It Sy Architecture Ta Sy void * Ta Sy long double Ta Sy time_t
|
|
.It amd64 Ta 8 Ta 16 Ta 8
|
|
.It arm Ta 4 Ta 8 Ta 8
|
|
.It armeb Ta 4 Ta 8 Ta 8
|
|
.It armv6 Ta 4 Ta 8 Ta 8
|
|
.It arm64 Ta 8 Ta 16 Ta 8
|
|
.It i386 Ta 4 Ta 12 Ta 4
|
|
.It mips Ta 4 Ta 8 Ta 8
|
|
.It mipsel Ta 4 Ta 8 Ta 8
|
|
.It mipselhf Ta 4 Ta 8 Ta 8
|
|
.It mipshf Ta 4 Ta 8 Ta 8
|
|
.It mipsn32 Ta 4 Ta 8 Ta 8
|
|
.It mips64 Ta 8 Ta 8 Ta 8
|
|
.It mips64el Ta 8 Ta 8 Ta 8
|
|
.It mips64elhf Ta 8 Ta 8 Ta 8
|
|
.It mips64hf Ta 8 Ta 8 Ta 8
|
|
.It powerpc Ta 4 Ta 8 Ta 8
|
|
.It powerpcspe Ta 4 Ta 8 Ta 8
|
|
.It powerpc64 Ta 8 Ta 8 Ta 8
|
|
.It riscv64 Ta 8 Ta 16 Ta 8
|
|
.It riscv64sf Ta 8 Ta 16 Ta 8
|
|
.It sparc64 Ta 8 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 "Sy Architecture" "Sy Endianness" "Sy char Signedness"
|
|
.It Sy Architecture Ta Sy Endianness Ta Sy char Signedness
|
|
.It amd64 Ta little Ta signed
|
|
.It arm Ta little Ta unsigned
|
|
.It armeb Ta big Ta unsigned
|
|
.It armv6 Ta little Ta unsigned
|
|
.It arm64 Ta little Ta unsigned
|
|
.It i386 Ta little Ta signed
|
|
.It mips Ta big Ta signed
|
|
.It mipsel Ta little Ta signed
|
|
.It mipselhf Ta little Ta signed
|
|
.It mipshf Ta big Ta signed
|
|
.It mipsn32 Ta big Ta signed
|
|
.It mips64 Ta big Ta signed
|
|
.It mips64el Ta little Ta signed
|
|
.It mips64elhf Ta little Ta signed
|
|
.It mips64hf Ta big Ta signed
|
|
.It powerpc Ta big Ta unsigned
|
|
.It powerpcspe Ta big Ta unsigned
|
|
.It powerpc64 Ta big Ta unsigned
|
|
.It riscv64 Ta little Ta signed
|
|
.It riscv64sf Ta little Ta signed
|
|
.It sparc64 Ta big Ta signed
|
|
.El
|
|
.Ss Page Size
|
|
.Bl -column -offset indent "Sy Architecture" "Sy Page Sizes"
|
|
.It Sy Architecture Ta Sy Page Sizes
|
|
.It amd64 Ta 4K, 2M, 1G
|
|
.It arm Ta 4K
|
|
.It armeb Ta 4K
|
|
.It armv6 Ta 4K, 1M
|
|
.It arm64 Ta 4K, 2M, 1G
|
|
.It i386 Ta 4K, 2M (PAE), 4M
|
|
.It mips Ta 4K
|
|
.It mipsel Ta 4K
|
|
.It mipselhf Ta 4K
|
|
.It mipshf Ta 4K
|
|
.It mipsn32 Ta 4K
|
|
.It mips64 Ta 4K
|
|
.It mips64el Ta 4K
|
|
.It mips64elhf Ta 4K
|
|
.It mips64hf Ta 4K
|
|
.It powerpc Ta 4K
|
|
.It powerpcspe Ta 4K
|
|
.It powerpc64 Ta 4K
|
|
.It riscv64 Ta 4K
|
|
.It riscv64sf Ta 4K
|
|
.It sparc64 Ta 8K
|
|
.El
|
|
.Ss Floating Point
|
|
.Bl -column -offset indent "Sy Architecture" "Sy float, double" "Sy long double"
|
|
.It Sy Architecture Ta Sy float, double Ta Sy long double
|
|
.It amd64 Ta hard Ta hard, 80 bit
|
|
.It arm Ta soft Ta soft, double precision
|
|
.It armeb Ta soft Ta soft, double precision
|
|
.It armv6 Ta hard(1) Ta hard, double precision
|
|
.It arm64 Ta hard Ta soft, quad precision
|
|
.It i386 Ta hard Ta hard, 80 bit
|
|
.It mips Ta soft Ta identical to double
|
|
.It mipsel Ta soft Ta identical to double
|
|
.It mipselhf Ta hard Ta identical to double
|
|
.It mipshf Ta hard Ta identical to double
|
|
.It mipsn32 Ta soft Ta identical to double
|
|
.It mips64 Ta soft Ta identical to double
|
|
.It mips64el Ta soft Ta identical to double
|
|
.It mips64elhf Ta hard Ta identical to double
|
|
.It mips64hf Ta hard Ta identical to double
|
|
.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 riscv64 Ta hard Ta hard, double precision
|
|
.It riscv64sf Ta soft Ta soft, double precision
|
|
.It sparc64 Ta hard Ta hard, quad precision
|
|
.El
|
|
.Pp
|
|
(1) Prior to
|
|
.Fx 11.0 ,
|
|
armv6 used the softfp ABI even though it supported only processors
|
|
with a floating point unit.
|
|
.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 "BYTE_ORDER" "Sy Meaning"
|
|
.It Sy Macro Ta Sy Meaning
|
|
.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 BYTE_ORDER Ta Either Dv BIG_ENDIAN or Dv LITTLE_ENDIAN .
|
|
.Dv PDP11_ENDIAN
|
|
is not used on
|
|
.Fx .
|
|
.El
|
|
.Pp
|
|
Architecture-specific macros:
|
|
.Bl -column -offset indent "Sy Architecture" "Sy Predefined macros"
|
|
.It Sy Architecture Ta Sy Predefined macros
|
|
.It amd64 Ta Dv __amd64__, Dv __x86_64__
|
|
.It arm Ta Dv __arm__
|
|
.It armeb Ta Dv __arm__
|
|
.It armv6 Ta Dv __arm__, Dv __ARM_ARCH >= 6
|
|
.It arm64 Ta Dv __aarch64__
|
|
.It i386 Ta Dv __i386__
|
|
.It mips Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_o32
|
|
.It mipsel Ta Dv __mips__, Dv __mips_o32
|
|
.It mipselhf Ta Dv __mips__, Dv __mips_o32
|
|
.It mipshf Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_o32
|
|
.It mipsn32 Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_n32
|
|
.It mips64 Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_n64
|
|
.It mips64el Ta Dv __mips__, Dv __mips_n64
|
|
.It mips64elhf Ta Dv __mips__, Dv __mips_n64
|
|
.It mips64hf Ta Dv __mips__, Dv __MIPSEB__, Dv __mips_n64
|
|
.It powerpc Ta Dv __powerpc__
|
|
.It powerpcspe Ta Dv __powerpc__, Dv __SPE__
|
|
.It powerpc64 Ta Dv __powerpc__, Dv __powerpc64__
|
|
.It riscv64 Ta Dv __riscv, Dv __riscv_xlen == 64
|
|
.It riscv64sf Ta Dv __riscv, Dv __riscv_xlen == 64
|
|
.It sparc64 Ta Dv __sparc64__
|
|
.El
|
|
.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 -column -offset indent "Sy Variable" "Sy Meaning and usage"
|
|
.It Dv MACHINE Represent 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 (e.g., MIPS' n32 ABI).
|
|
It, along with
|
|
.Dv MACHINE ,
|
|
defines the ABI used by the system.
|
|
For example, the MIPS CPU processor family supports 9 different
|
|
combinations encoding pointer size, endian and hard versus soft float (for
|
|
8 combinations) as well as N32 (which only ever had one variation of
|
|
all these).
|
|
Generally, the plain CPU name specifies the most common (or at least
|
|
first) variant of the CPU.
|
|
This is why mips and mips64 imply 'big endian' while 'arm' and 'armv7'
|
|
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 speifies the 64-bit evolution of the x86
|
|
platform (it matches the 'first rule') as everybody else uses x86_64.
|
|
There is no standard name for the processor: each OS selects its own
|
|
conventions.
|
|
.It Dv MACHINE_CPUARCH Represents the source location for a given
|
|
.Dv MACHINE_ARCH .
|
|
For example,
|
|
.Dv MACHINE_CPUARCH
|
|
is defined to be mips for all the flavors of mips that we support
|
|
since we support them all with a shared set of sources.
|
|
While amd64 and i386 are closely related, MACHINE_CPUARCH is not x86
|
|
for them.
|
|
The FreeBSD 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 hysterical raisons).
|
|
.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 src.conf 5 ,
|
|
.Xr build 7
|
|
.Sh HISTORY
|
|
An
|
|
.Nm
|
|
manual page appeared in
|
|
.Fx 12 .
|