share/man/man4/smp.4

   1 .\" Copyright (c) 1997
   2 .\"     Steve Passe <fsmp@FreeBSD.org>.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. The name of the developer may NOT be used to endorse or promote products
  10 .\"    derived from this software without specific prior written permission.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd January 4, 2019
  27 .Dt SMP 4
  28 .Os
  29 .Sh NAME
  30 .Nm SMP
  31 .Nd description of the FreeBSD Symmetric Multi-Processor kernel
  32 .Sh SYNOPSIS
  33 .Cd options SMP
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 kernel implements symmetric multi-processor support.
  38 .Pp
  39 .Nm
  40 support can be disabled by setting the loader tunable
  41 .Va kern.smp.disabled
  42 to 1.
  43 .Pp
  44 The number of CPUs detected by the system is available in
  45 the read-only sysctl variable
  46 .Va hw.ncpu .
  47 .Pp
  48 The number of online threads per CPU core is available in the read-only sysctl
  49 variable
  50 .Va kern.smp.threads_per_core .
  51 The number of physical CPU cores detected by the system is available in the
  52 read-only sysctl variable
  53 .Va kern.smp.cores .
  54 .Pp
  55 .Fx
  56 allows specific CPUs on a multi-processor system to be disabled.
  57 This can be done using the
  58 .Va hint.lapic.X.disabled
  59 tunable, where X is the APIC ID of a CPU.
  60 Setting this tunable to 1 will result in the corresponding CPU being
  61 disabled.
  62 .Pp
  63 .Fx
  64 supports simultaneous multithreading on x86 and powerpc platforms.
  65 On x86, the logical CPUs can be disabled by setting the
  66 .Va machdep.hyperthreading_allowed
  67 tunable to zero.
  68 .Pp
  69 The
  70 .Xr sched_ule 4
  71 scheduler implements CPU topology detection and adjusts the scheduling
  72 algorithms to make better use of modern multi-core CPUs.
  73 The sysctl variable
  74 .Va kern.sched.topology_spec
  75 reflects the detected CPU hardware in a parsable XML format.
  76 The top level XML tag is <groups>, which encloses one or more <group> tags
  77 containing data about individual CPU groups.
  78 A CPU group contains CPUs that are detected to be "close" together, usually
  79 by being cores in a single multi-core processor.
  80 Attributes available in a <group> tag are "level", corresponding to the
  81 nesting level of the CPU group and "cache-level", corresponding to the
  82 level of CPU caches shared by the CPUs in the group.
  83 The <group> tag contains the <cpu> and <flags> tags.
  84 The <cpu> tag describes CPUs in the group.
  85 Its attributes are "count", corresponding to the number of CPUs in the
  86 group and "mask", corresponding to the integer binary mask in which
  87 each bit position set to 1 signifies a CPU belonging to the group.
  88 The contents (CDATA) of the <cpu> tag is the comma-delimited list
  89 of CPU indexes (derived from the "mask" attribute).
  90 The <flags> tag contains special tags (if any) describing the relation
  91 of the CPUs in the group.
  92 The possible flags are currently "HTT" and "SMT", corresponding to
  93 the various implementations of hardware multithreading.
  94 An example topology_spec output for a system consisting of
  95 two quad-core processors is:
  96 .Bd -literal
  97 <groups>
  98   <group level="1" cache-level="0">
  99     <cpu count="8" mask="0xff">0, 1, 2, 3, 4, 5, 6, 7</cpu>
 100     <flags></flags>
 101     <children>
 102       <group level="2" cache-level="0">
 103         <cpu count="4" mask="0xf">0, 1, 2, 3</cpu>
 104         <flags></flags>
 105       </group>
 106       <group level="2" cache-level="0">
 107         <cpu count="4" mask="0xf0">4, 5, 6, 7</cpu>
 108         <flags></flags>
 109       </group>
 110     </children>
 111   </group>
 112 </groups>
 113 .Ed
 114 .Pp
 115 This information is used internally by the kernel to schedule related
 116 tasks on CPUs that are closely grouped together.
 117 .Sh COMPATIBILITY
 118 Support for multi-processor systems is present for all Tier-1 and Tier-2
 119 architectures on
 120 .Fx .
 121 Currently, this includes x86, powerpc, mips, arm and arm64.
 122 Support is enabled using
 123 .Cd options SMP .
 124 It is permissible to use the SMP kernel configuration on non-SMP hardware.
 125 .Sh I386 NOTES
 126 For i386 systems, the
 127 .Nm
 128 kernel supports motherboards that follow the Intel MP specification,
 129 version 1.4.
 130 In addition to
 131 .Cd options SMP ,
 132 i386 also requires
 133 .Cd device apic .
 134 The
 135 .Xr mptable 1
 136 command may be used to view the status of multi-processor support.
 137 .Sh SEE ALSO
 138 .Xr cpuset 1 ,
 139 .Xr mptable 1 ,
 140 .Xr sched_4bsd 4 ,
 141 .Xr sched_ule 4 ,
 142 .Xr loader 8 ,
 143 .Xr sysctl 8 ,
 144 .Xr condvar 9 ,
 145 .Xr msleep 9 ,
 146 .Xr mtx_pool 9 ,
 147 .Xr mutex 9 ,
 148 .Xr rwlock 9 ,
 149 .Xr sema 9 ,
 150 .Xr sx 9
 151 .Sh HISTORY
 152 The
 153 .Nm
 154 kernel's early history is not (properly) recorded.
 155 It was developed
 156 in a separate CVS branch until April 26, 1997, at which point it was
 157 merged into 3.0-current.
 158 By this date 3.0-current had already been
 159 merged with Lite2 kernel code.
 160 .Pp
 161 .Fx 5.0
 162 introduced support for a host of new synchronization primitives, and
 163 a move towards fine-grained kernel locking rather than reliance on
 164 a Giant kernel lock.
 165 The SMPng Project relied heavily on the support of BSDi, who provided
 166 reference source code from the fine-grained SMP implementation found
 167 in
 168 .Bsx .
 169 .Pp
 170 .Fx 5.0
 171 also introduced support for SMP on the sparc64 architecture.
 172 .Sh AUTHORS
 173 .An Steve Passe Aq Mt fsmp@FreeBSD.org
 174 .Sh CAVEATS
 175 The
 176 .Va kern.smp.threads_per_core
 177 and
 178 .Va kern.smp.cores
 179 sysctl variables are provided as a best-effort guess.
 180 If an architecture or platform adds SMT and
 181 .Fx
 182 has not yet implemented detection, the reported values may be inaccurate.
 183 In this case,
 184 .Va kern.smp.threads_per_core
 185 will report
 186 .Dv 1
 187 and
 188 .Va kern.smp.cores
 189 will report the same value as
 190 .Va hw.ncpu .