share/man/man9/domainset.9

   1 .\" Copyright (c) 2018 Jeffrey Roberson <jeff@FreeBSD.org>
   2 .\" 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. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
  14 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  15 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE
  17 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  18 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  19 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  20 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  21 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  22 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  23 .\" POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd October 30, 2018
  28 .Dt DOMAINSET 9
  29 .Os
  30 .Sh NAME
  31 .Nm domainset(9)
  32 .Nd domainset functions and operation
  33 .Sh SYNOPSIS
  34 .In sys/_domainset.h
  35 .In sys/domainset.h
  36 .\"
  37 .Bd -literal -offset indent
  38 struct domainset {
  39         domainset_t     ds_mask;
  40         uint16_t        ds_policy;
  41         domainid_t      ds_prefer;
  42         ...
  43 };
  44 .Ed
  45 .Pp
  46 .Ft struct domainset *
  47 .Fn DOMAINSET_FIXED domain
  48 .Ft struct domainset *
  49 .Fn DOMAINSET_RR
  50 .Ft struct domainset *
  51 .Fn DOMAINSET_PREF domain
  52 .Ft struct domainset *
  53 .Fn domainset_create "const struct domainset *key"
  54 .Ft int
  55 .Fn sysctl_handle_domainset "SYSCTL_HANDLER_ARGS"
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 API provides memory domain allocation policy for NUMA machines.
  60 Each
  61 .Vt domainset
  62 contains a bitmask of allowed domains, an integer policy, and an optional
  63 preferred domain.
  64 Together, these specify a search order for memory allocations as well as
  65 the ability to restrict threads and objects to a subset of available
  66 memory domains for system partitioning and resource management.
  67 .Pp
  68 Every thread in the system and optionally every
  69 .Vt vm_object_t ,
  70 which is used to represent files and other memory sources, has
  71 a reference to a
  72 .Vt struct domainset .
  73 The domainset associated with the object is consulted first and the system
  74 falls back to the thread policy if none exists.
  75 .Pp
  76 The allocation policy has the following possible values:
  77 .Bl -tag -width "foo"
  78 .It Dv DOMAINSET_POLICY_ROUNDROBIN
  79 Memory is allocated from each domain in the mask in a round-robin fashion.
  80 This distributes bandwidth evenly among available domains.
  81 This policy can specify a single domain for a fixed allocation.
  82 .It Dv DOMAINSET_POLICY_FIRSTTOUCH
  83 Memory is allocated from the node that it is first accessed on.
  84 Allocation falls back to round-robin if the current domain is not in the
  85 allowed set or is out of memory.
  86 This policy optimizes for locality but may give pessimal results if the
  87 memory is accessed from many CPUs that are not in the local domain.
  88 .It Dv DOMAINSET_POLICY_PREFER
  89 Memory is allocated from the node in the
  90 .Vt prefer
  91 member.
  92 The preferred node must be set in the allowed mask.
  93 If the preferred node is out of memory the allocation falls back to
  94 round-robin among allowed sets.
  95 .It Dv DOMAINSET_POLICY_INTERLEAVE
  96 Memory is allocated in a striped fashion with multiple pages
  97 allocated to each domain in the set according to the offset within
  98 the object.
  99 The strip width is object dependent and may be as large as a
 100 super-page (2MB on amd64).
 101 This gives good distribution among memory domains while keeping system
 102 efficiency higher and is preferential to round-robin for general use.
 103 .El
 104 .Pp
 105 The
 106 .Fn DOMAINSET_FIXED ,
 107 .Fn DOMAINSET_RR
 108 and
 109 .Fn DOMAINSET_PREF
 110 macros provide pointers to global pre-defined policies for use when the
 111 desired policy is known at compile time.
 112 .Fn DOMAINSET_FIXED
 113 is a policy which only permits allocations from the specified domain.
 114 .Fn DOMAINSET_RR
 115 provides round-robin selection among all domains in the system.
 116 The
 117 .Fn DOMAINSET_PREF
 118 policies attempt allocation from the specified domain, but unlike
 119 .Fn DOMAINSET_FIXED
 120 will fall back to other domains to satisfy the request.
 121 These policies should be used in preference to
 122 .Fn DOMAINSET_FIXED
 123 to avoid blocking indefinitely on a
 124 .Dv M_WAITOK
 125 request.
 126 The
 127 .Fn domainset_create
 128 function takes a partially filled in domainset as a key and returns a
 129 valid domainset or NULL.
 130 It is critical that consumers not use domainsets that have not been
 131 returned by this function.
 132 .Vt domainset
 133 is an immutable type that is shared among all matching keys and must
 134 not be modified after return.
 135 .Pp
 136 The
 137 .Fn sysctl_handle_domainset
 138 function is provided as a convenience for modifying or viewing domainsets
 139 that are not accessible via
 140 .Xr cpuset 2 .
 141 It is intended for use with
 142 .Xr sysctl 9 .
 143 .Sh SEE ALSO
 144 .Xr cpuset 1 ,
 145 .Xr cpuset 2 ,
 146 .Xr cpuset_setdomain 2 ,
 147 .Xr bitset 9
 148 .Sh HISTORY
 149 .In sys/domainset.h
 150 first appeared in
 151 .Fx 12.0 .