Page MenuHomeFreeBSD
Files F153983202

D56548.id175965.diff
No OneTemporary
Actions

D56548.id175965.diff
View Options

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -209,6 +209,7 @@
hidquirk.4 \
hidraw.4 \
hkbd.4 \
+ hmp.4 \
hms.4 \
hmt.4 \
hpen.4 \
@@ -737,6 +738,7 @@
MLINKS+=gpioths.4 dht11.4
MLINKS+=gpioths.4 dht22.4
MLINKS+=gre.4 if_gre.4
+MLINKS+=hmp.4 HMP.4
MLINKS+=hpet.4 acpi_hpet.4
MLINKS+=${_hv_netvsc.4} ${_hn.4} \
${_hv_netvsc.4} ${_if_hn.4}
diff --git a/share/man/man4/hmp.4 b/share/man/man4/hmp.4
new file mode 100644
--- /dev/null
+++ b/share/man/man4/hmp.4
@@ -0,0 +1,213 @@
+.\"
+.\" Copyright (c) 2026 FreeBSD Foundation
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause
+.\"
+.\" Author: Minsoo Choo <minsoochoo0122@proton.me>
+.\"
+.Dd April 21, 2026
+.Dt HMP 4
+.Os
+.Sh NAME
+.Nm HMP
+.Nd description of the FreeBSD Heterogeneous Multi-Processing kernel support
+.Sh SYNOPSIS
+.Cd options HMP
+.Sh DESCRIPTION
+The
+.Nm
+framework provides kernel support for heterogeneous multi-processor systems,
+where CPUs in the same system differ in their performance and/or efficiency
+characteristics.
+Such systems include Arm big.LITTLE and DynamIQ designs, Intel hybrid
+processors combining Performance-cores and Efficient-cores, and other
+asymmetric multi-processor architectures.
+.Pp
+The
+.Nm
+framework exposes two distinct notions of CPU capability to the scheduler:
+.Bl -tag -width "perf_score"
+.It Va capacity
+A static, boot-time value describing the relative throughput of each CPU,
+derived from its microarchitecture and maximum frequency.
+It is used by the load balancer to distribute work proportionally across
+heterogeneous CPUs.
+.It Va perf_score
+A dynamic value describing the current performance capability of a CPU
+(higher means faster).
+It is updated at runtime and is read by the scheduler when placing
+interactive or real-time threads.
+.It Va eff_score
+A dynamic value describing the current efficiency capability of a CPU
+(higher means less power per unit of work).
+It is updated alongside
+.Va perf_score
+and is read by the scheduler when placing background and idle-priority
+threads.
+.El
+.Pp
+All capability values are normalized to the range 0 to
+.Dv HMP_CAPACITY_SCALE
+(1024), allowing a single scale to represent values reported by different
+hardware interfaces such as ACPI CPPC (0-255), Intel HFI (0-255), and
+Arm capacity (0-1024).
+.Pp
+In addition to scores, each CPU carries a set of flags.
+The
+.Dv HMP_FLAG_DYNAMIC
+flag indicates that the CPU provides runtime-updated scores.
+The
+.Dv HMP_FLAG_THROTTLED
+flag is set by the provider when performance is currently constrained
+by thermal or power-budget limits;
+the scheduler uses this hint to steer time-sharing threads away from
+throttled CPUs.
+.Sh PROVIDERS
+The
+.Nm
+framework is driven by
+.Em providers ,
+which are pluggable backends responsible for discovering CPU capabilities
+and keeping scores up to date.
+A provider supplies two callbacks:
+.Bl -tag -width "probe()"
+.It Fn probe
+Returns true if the provider can run on the current system.
+Providers must not modify any per-CPU state during probing.
+.It Fn init
+Populates capacity, scores, and flags for every online CPU.
+Called exactly once, on the winning provider only.
+.El
+.Pp
+Providers are registered at
+.Dv SI_SUB_SMP
+via the
+.Fn HMP_PROVIDER_DECLARE
+macro.
+During initialization at
+.Dv SI_SUB_SMP + 1 ,
+every registered provider is probed and the one with the highest priority
+among those that probed successfully is selected as the active provider.
+A built-in
+.Dq default
+provider with priority 0 is always present and always probes successfully;
+it assigns
+.Dv HMP_CAPACITY_DEFAULT
+to every CPU and reports no dynamic scores, yielding behavior equivalent
+to a homogeneous system.
+.Pp
+Typical higher-priority providers include backends for ACPI CPPC,
+Intel Hardware Feedback Interface (HFI), and Arm SCMI.
+.Sh SYSCTL VARIABLES
+The
+.Nm
+framework exposes its state through the
+.Va kern.hmp
+sysctl tree.
+.Pp
+System-wide variables:
+.Bl -tag -width "kern.hmp.active_provider"
+.It Va kern.hmp.total_capacity
+Sum of the per-CPU capacities, normalized to
+.Dv HMP_CAPACITY_SCALE .
+.It Va kern.hmp.has_scores
+True if at least one CPU provides dynamic performance or efficiency scores.
+.It Va kern.hmp.active_provider
+Name of the currently active provider.
+.El
+.Pp
+Per-CPU variables, available under
+.Va kern.hmp.cpu.<N>
+for each CPU
+.Ar N :
+.Bl -tag -width "capacity_percent"
+.It Va capacity
+Static capacity in the range 0 to
+.Dv HMP_CAPACITY_SCALE .
+.It Va capacity_percent
+Static capacity expressed as a percentage of the scale.
+.It Va perf_score
+Current dynamic performance score.
+.It Va eff_score
+Current dynamic efficiency score.
+.It Va flags
+Non-zero if the CPU reports dynamic scores
+.Pq Dv HMP_FLAG_DYNAMIC .
+.It Va throttled
+Non-zero if the CPU is currently throttled due to thermal or power
+constraints
+.Pq Dv HMP_FLAG_THROTTLED .
+.El
+.Pp
+Per-provider variables, available under
+.Va kern.hmp.provider.<name>
+for every registered provider (not just the active one):
+.Bl -tag -width "priority"
+.It Va priority
+Provider priority; the highest-priority probed provider becomes active.
+.It Va probed
+True if the provider's
+.Fn probe
+callback returned true on this system.
+.It Va active
+True if the provider was selected as the active provider.
+.El
+.Sh IMPLEMENTATION NOTES
+Per-CPU state is stored in a
+.Vt DPCPU
+area of type
+.Vt struct hmp_pcpu .
+Capacity is written once at initialization and never subsequently modified,
+so it may be read without synchronization.
+Scores and flags are written by a single provider and read locklessly by
+the scheduler;
+accessor and setter functions
+.Fn ( hmp_score , hmp_flag , hmp_set_score , hmp_set_flags , hmp_clear_flags )
+use acquire/release atomic operations to ensure consistent visibility
+without requiring the scheduler to take locks on hot paths.
+.Pp
+The scheduler helpers
+.Fn hmp_highest_capacity_cpu
+and
+.Fn hmp_best_cpu
+iterate over a CPU mask and return, respectively, the CPU with the highest
+static capacity and the CPU with the highest dynamic score of the requested
+type.
+When no provider publishes dynamic scores,
+.Fn hmp_best_cpu
+transparently falls back to
+.Fn hmp_highest_capacity_cpu .
+Both helpers run in O(n) time in the number of CPUs;
+a score snapshot may briefly be inconsistent if a provider updates a score
+mid-traversal, but the resulting placement drift is negligible compared to
+the cost of taking a global lock.
+.Sh COMPATIBILITY
+.Nm
+requires and is enabled with
+.Cd options HMP .
+It is safe to enable
+.Nm
+on homogeneous hardware:
+the default provider will assign equal capacity to every CPU, and the
+scheduler will behave as if
+.Nm
+were disabled.
+.Sh SEE ALSO
+.Xr cpuset 1 ,
+.Xr sched_4bsd 4 ,
+.Xr sched_ule 4 ,
+.Xr smp 4 ,
+.Xr sysctl 8
+.Sh HISTORY
+The
+.Nm
+framework first appeared in
+.Fx 15.1 .
+.Sh AUTHORS
+The
+.Nm
+framework was developed by
+.An Minsoo Choo Aq Mt minsoochoo0122@proton.me
+under sponsorship from the
+.Fx
+Foundation.

File Metadata

Mime Type
text/plain
Expires
Sun, Apr 26, 6:21 AM (8 h, 23 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
32168691
Default Alt Text
D56548.id175965.diff (6 KB)

Event Timeline