.\" Copyright (c) 2018 Jeffrey Roberson <jeff@FreeBSD.org>
.\" All rights reserved.
.\"
.\" 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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 April 14, 2021
.Dt DOMAINSET 9
.Os
.Sh NAME
.Nm domainset(9)
.Nd domainset functions and operation
.Sh SYNOPSIS
.In sys/_domainset.h
.In sys/domainset.h
.\"
.Bd -literal -offset indent
struct domainset {
domainset_t ds_mask;
uint16_t ds_policy;
domainid_t ds_prefer;
...
};
.Ed
.Pp
.Ft struct domainset *
.Fn DOMAINSET_FIXED domain
.Ft struct domainset *
.Fn DOMAINSET_FT
.Ft struct domainset *
.Fn DOMAINSET_IL
.Ft struct domainset *
.Fn DOMAINSET_RR
.Ft struct domainset *
.Fn DOMAINSET_PREF domain
.Ft struct domainset *
.Fn domainset_create "const struct domainset *key"
.Ft int
.Fn sysctl_handle_domainset "SYSCTL_HANDLER_ARGS"
.Sh DESCRIPTION
The
.Nm
API provides memory domain allocation policy for NUMA machines.
Each
.Vt domainset
contains a bitmask of allowed domains, an integer policy, and an optional
preferred domain.
Together, these specify a search order for memory allocations as well as
the ability to restrict threads and objects to a subset of available
memory domains for system partitioning and resource management.
.Pp
Every thread in the system and optionally every
.Vt vm_object_t ,
which is used to represent files and other memory sources, has
a reference to a
.Vt struct domainset .
The domainset associated with the object is consulted first and the system
falls back to the thread policy if none exists.
.Pp
The allocation policy has the following possible values:
.Bl -tag -width "foo"
.It Dv DOMAINSET_POLICY_ROUNDROBIN
Memory is allocated from each domain in the mask in a round-robin fashion.
This distributes bandwidth evenly among available domains.
This policy can specify a single domain for a fixed allocation.
.It Dv DOMAINSET_POLICY_FIRSTTOUCH
Memory is allocated from the node that it is first accessed on.
Allocation falls back to round-robin if the current domain is not in the
allowed set or is out of memory.
This policy optimizes for locality but may give pessimal results if the
memory is accessed from many CPUs that are not in the local domain.
.It Dv DOMAINSET_POLICY_PREFER
Memory is allocated from the node in the
.Vt prefer
member.
The preferred node must be set in the allowed mask.
If the preferred node is out of memory the allocation falls back to
round-robin among allowed sets.
.It Dv DOMAINSET_POLICY_INTERLEAVE
Memory is allocated in a striped fashion with multiple pages
allocated to each domain in the set according to the offset within
the object.
The strip width is object dependent and may be as large as a
super-page (2MB on amd64).
This gives good distribution among memory domains while keeping system
efficiency higher and is preferential to round-robin for general use.
.El
.Pp
The
.Fn DOMAINSET_FIXED ,
.Fn DOMAINSET_FT ,
.Fn DOMAINSET_IL ,
.Fn DOMAINSET_RR
and
.Fn DOMAINSET_PREF
macros provide pointers to global pre-defined policies for use when the
desired policy is known at compile time.
.Fn DOMAINSET_FIXED
is a policy which only permits allocations from the specified domain.
.Fn DOMAINSET_FT
is a policy which attempts to allocate memory local to the current CPU,
falling back to a round-robin policy if the initial allocation fails.
.Fn DOMAINSET_IL
and
.Fn DOMAINSET_RR
provide round-robin selection among all domains in the system, corresponding
to the
.Dv DOMAINSET_POLICY_INTERLEAVE
and
.Dv DOMAINSET_POLICY_ROUNDROBIN
policies, respectively.
The
.Fn DOMAINSET_PREF
policies attempt allocation from the specified domain, but unlike
.Fn DOMAINSET_FIXED
will fall back to other domains to satisfy the request.
These policies should be used in preference to
.Fn DOMAINSET_FIXED
to avoid blocking indefinitely on a
.Dv M_WAITOK
request.
The
.Fn domainset_create
function takes a partially filled in domainset as a key and returns a
valid domainset or NULL.
It is critical that consumers not use domainsets that have not been
returned by this function.
.Vt domainset
is an immutable type that is shared among all matching keys and must
not be modified after return.
.Pp
The
.Fn sysctl_handle_domainset
function is provided as a convenience for modifying or viewing domainsets
that are not accessible via
.Xr cpuset 2 .
It is intended for use with
.Xr sysctl 9 .
.Sh SEE ALSO
.Xr cpuset 1 ,
.Xr cpuset 2 ,
.Xr cpuset_setdomain 2 ,
.Xr bitset 9
.Sh HISTORY
.In sys/domainset.h
first appeared in
.Fx 12.0 .
