355 lines
8.3 KiB
Groff
355 lines
8.3 KiB
Groff
.\" $NetBSD: kcpuset.9,v 1.9 2014/03/18 18:20:40 riastradh Exp $ */
|
|
.\"
|
|
.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen.iki.fi>
|
|
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 July 17, 2013
|
|
.Dt KCPUSET 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm kcpuset ,
|
|
.Nm kcpuset_create ,
|
|
.Nm kcpuset_destroy ,
|
|
.Nm kcpuset_clone ,
|
|
.Nm kcpuset_copy ,
|
|
.Nm kcpuset_use ,
|
|
.Nm kcpuset_unuse ,
|
|
.Nm kcpuset_copyin ,
|
|
.Nm kcpuset_copyout ,
|
|
.Nm kcpuset_zero ,
|
|
.Nm kcpuset_fill ,
|
|
.Nm kcpuset_set ,
|
|
.Nm kcpuset_clear ,
|
|
.Nm kcpuset_isset ,
|
|
.Nm kcpuset_isotherset ,
|
|
.Nm kcpuset_iszero ,
|
|
.Nm kcpuset_match ,
|
|
.Nm kcpuset_intersect ,
|
|
.Nm kcpuset_merge ,
|
|
.Nm kcpuset_remove ,
|
|
.Nm kcpuset_ffs ,
|
|
.Nm kcpuset_ffs_intersecting ,
|
|
.Nm kcpuset_countset ,
|
|
.Nm kcpuset_atomic_set ,
|
|
.Nm kcpuset_atomic_clear ,
|
|
.Nm kcpuset_atomicly_intersect ,
|
|
.Nm kcpuset_atomicly_merge ,
|
|
.Nm kcpuset_atomicly_remove ,
|
|
.Nm kcpuset_export_32
|
|
.Nd dynamic kernel CPU sets
|
|
.Sh SYNOPSIS
|
|
.In sys/kcpuset.h
|
|
.Ft void
|
|
.Fn kcpuset_create "kcpuset_t **retkcp" "bool zero"
|
|
.Ft void
|
|
.Fn kcpuset_destroy "kcpuset_t *kcp"
|
|
.Ft void
|
|
.Fn kcpuset_clone "kcpuset_t **retkcp" "const kcpuset_t *skcp"
|
|
.Ft void
|
|
.Fn kcpuset_copy "kcpuset_t *dkcp" "const kcpuset_t *skcp"
|
|
.Ft void
|
|
.Fn kcpuset_use "kcpuset_t *kcp"
|
|
.Ft void
|
|
.Fn kcpuset_unuse "kcpuset_t *kcp" "kcpuset_t **lst"
|
|
.Ft int
|
|
.Fn kcpuset_copyin "const cpuset_t *ucp" "kcpuset_t *kcp" "size_t len"
|
|
.Ft int
|
|
.Fn kcpuset_copyout "kcpuset_t *kcp" "cpuset_t *ucp" "size_t len"
|
|
.Ft void
|
|
.Fn kcpuset_zero "kcpuset_t *kcp"
|
|
.Ft void
|
|
.Fn kcpuset_fill "kcpuset_t *kcp"
|
|
.Ft void
|
|
.Fn kcpuset_set "kcpuset_t *kcp" "cpuid_t cpu"
|
|
.Ft void
|
|
.Fn kcpuset_clear "kcpuset_t *kcp" "cpuid_t cpu"
|
|
.Ft bool
|
|
.Fn kcpuset_isset "const kcpuset_t * kcp" "cpuid_t cpu"
|
|
.Ft bool
|
|
.Fn kcpuset_isotherset "const kcpuset_t * kcp" "cpuid_t cpu"
|
|
.Ft bool
|
|
.Fn kcpuset_iszero "const kcpuset_t *kcp"
|
|
.Ft bool
|
|
.Fn kcpuset_intersecting_p "const kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft bool
|
|
.Fn kcpuset_match "const kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft void
|
|
.Fn kcpuset_intersect "kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft void
|
|
.Fn kcpuset_merge "kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft void
|
|
.Fn kcpuset_remove "kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft cpuid_t
|
|
.Fn kcpuset_ffs "const kcpuset_t *kcp"
|
|
.Ft cpuid_t
|
|
.Fn kcpuset_ffs_intersecting "const kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft int
|
|
.Fn kcpuset_countset "const kcpuset_t *kcp"
|
|
.Ft void
|
|
.Fn kcpuset_atomic_set "kcpuset_t *kcp" "cpuid_t cpu"
|
|
.Ft void
|
|
.Fn kcpuset_atomic_clear "kcpuset_t *kcp" "cpuid_t cpu"
|
|
.Ft void
|
|
.Fn kcpuset_atomicly_intersect "kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft void
|
|
.Fn kcpuset_atomicly_merge "kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft void
|
|
.Fn kcpuset_atomicly_remove "kcpuset_t *kcp1" "const kcpuset_t *kcp2"
|
|
.Ft void
|
|
.Fn kcpuset_export_u32 "const kcpuset_t *kcp" "uint32_t *bitfield" "size_t len"
|
|
.Sh DESCRIPTION
|
|
The machine-independent
|
|
.Nm
|
|
subsystem provides support for dynamic processor sets.
|
|
Conceptually
|
|
.Nm
|
|
can be understood to be the kernel equivalent of the user space
|
|
.Xr cpuset 3
|
|
interface.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width compact
|
|
.It Fn kcpuset_create "retkcp" "zero"
|
|
The
|
|
.Fn kcpuset_create
|
|
function creates a dynamic
|
|
.Tn CPU
|
|
set and stores the result to
|
|
.Fa retkcp .
|
|
If the boolean
|
|
.Fa zero
|
|
is not false, the allocated set is also initialized to zero.
|
|
.It Fn kcpuset_destroy "kcp"
|
|
Destroys the
|
|
.Tn CPU
|
|
set
|
|
.Fa kcp
|
|
and schedules any linked CPU sets for deferred destruction.
|
|
.It Fn kcpuset_copy "dkcp" "skcp"
|
|
Copies the
|
|
.Tn CPU
|
|
set pointed by
|
|
.Fa skcp
|
|
to
|
|
.Fa dkcp .
|
|
.It Fn kcpuset_clone "retkcp" "skcp"
|
|
Creates a dynamic
|
|
.Tn CPU
|
|
set and stores the result to
|
|
.Fa retkcp
|
|
and copies the
|
|
.Tn CPU
|
|
set pointed by
|
|
.Fa skcp
|
|
to the new
|
|
.Tn CPU
|
|
set.
|
|
.It Fn kcpuset_use "kcp"
|
|
Marks
|
|
.Fa kcp
|
|
as being in use by increasing the reference count of the object.
|
|
Note that initially
|
|
.Fn kcpuset_create
|
|
sets the reference count to 1.
|
|
.It Fn kcpuset_unuse "kcp" "lst"
|
|
Decreases the internal reference count of
|
|
.Fa kcp ,
|
|
and on the last reference (when the count reaches zero), destroys
|
|
.Fa kcp .
|
|
If
|
|
.Fa lst
|
|
is not
|
|
.Dv NULL ,
|
|
then instead of destroying,
|
|
.Fa kcp
|
|
will be added to the
|
|
.Fa lst
|
|
list for a deferred destruction.
|
|
.It Fn kcpuset_copyin "ucp" "kcp" "len"
|
|
Copies the
|
|
.Fa len
|
|
bytes long user-space
|
|
.Tn CPU
|
|
set
|
|
.Fa ucp
|
|
to the kernel
|
|
.Tn CPU
|
|
set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_copyout "kcp" "ucp" "len"
|
|
Copies the kernel
|
|
.Tn CPU
|
|
set
|
|
.Fa kcp
|
|
to the user-space
|
|
.Tn CPU
|
|
set
|
|
.Fa ucp .
|
|
.It Fn kcpuset_zero "kcp"
|
|
Clears the set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_fill "kcp"
|
|
Fills the whole set
|
|
.Fa kcp
|
|
with ones.
|
|
.It Fn kcpuset_set "kcp" "cpu"
|
|
Adds
|
|
.Fa cpu
|
|
to the set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_clear "kcp" "cpu"
|
|
Removes
|
|
.Fa cpu
|
|
from the set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_isset "kcp" "cpu"
|
|
Returns true if
|
|
.Fa cpu
|
|
is part of the
|
|
.Tn CPU
|
|
set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_isotherset "kcp" "cpu"
|
|
Returns true if there any CPUs
|
|
other than
|
|
.Fa cpu
|
|
in the
|
|
.Tn CPU
|
|
set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_iszero "kcp"
|
|
Returns true if the set
|
|
.Fa kcp
|
|
is empty.
|
|
.It Fn kcpuset_match "kcp1" "kcp2"
|
|
Compares the sets
|
|
.Fa kcp1
|
|
and
|
|
.Fa kcp2 ,
|
|
returning true if these are identical.
|
|
.It Fn kcpuset_intersect "kcp1" "kcp2"
|
|
Removes any
|
|
.Tn CPU
|
|
not set in
|
|
.Fa kcp2
|
|
from the set
|
|
.Fa kcp1 .
|
|
.It Fn kcpuset_merge "kcp1" "kcp2"
|
|
Merges the set
|
|
.Fa kcp2
|
|
to the set
|
|
.Fa kcp1 .
|
|
.It Fn kcpuset_remove "kcp1" "kcp2"
|
|
Removes any
|
|
.Tn CPU
|
|
present in
|
|
.Fa kcp2
|
|
from the set
|
|
.Fa kcp1 .
|
|
.It Fn kcpuset_ffs "kcp"
|
|
Returns the lowest numbered
|
|
.Ft cpu
|
|
present in
|
|
.Fa kcp
|
|
plus 1.
|
|
If
|
|
.Fa kcp
|
|
is empty, a value of 0 is returned.
|
|
.Fa kcp
|
|
.It Fn kcpuset_ffs_intersecting "kcp1" "kcp2"
|
|
Returns the lowest numbered
|
|
.Ft cpu
|
|
present in the intersection of
|
|
.Fa kcp1
|
|
and
|
|
.Fa kcp2
|
|
plus 1.
|
|
If the intersection is empty, a value of 0 is returned.
|
|
.It Fn kcpuset_countset "kcp"
|
|
Counts how many CPUs are in the set
|
|
.Fa kcp .
|
|
.It Fn kcpuset_atomic_set "kcp" "cpu"
|
|
The
|
|
.Fn kcpuset_atomic_set
|
|
function operates as
|
|
.Fn kcpuset_set ,
|
|
but the operation is atomic; see
|
|
.Xr atomic_ops 3
|
|
for more details.
|
|
.It Fn kcpuset_atomic_clear "kcp" "cpu"
|
|
Removes
|
|
.Fa cpu
|
|
from the
|
|
.Tn CPU
|
|
set
|
|
.Fa kcp
|
|
atomically.
|
|
.It Fn kcpuset_atomicly_intersect "kcp1" "kcp2"
|
|
The
|
|
.Fn kcpuset_atomicly_intersect
|
|
function operates as
|
|
.Fn kcpuset_intersect ,
|
|
but the operation is performed using atomic operations; see
|
|
.Xr atomic_ops 3
|
|
for more details.
|
|
.It Fn kcpuset_atomicly_merge "kcp1" "kcp2"
|
|
The
|
|
.Fn kcpuset_atomicly_merge
|
|
function operates as
|
|
.Fn kcpuset_merge ,
|
|
but the operation is performed using atomic operations; see
|
|
.Xr atomic_ops 3
|
|
for more details.
|
|
.It Fn kcpuset_atomicly_remove "kcp1" "kcp2"
|
|
The
|
|
.Fn kcpuset_atomicly_remove
|
|
function operates as
|
|
.Fn kcpuset_remove ,
|
|
but the operation is performed using atomic operations; see
|
|
.Xr atomic_ops 3
|
|
for more details.
|
|
.It Fn kcpuset_export_u32 "kcp" "bitfield" "len"
|
|
Exports the CPU set
|
|
.Fa kcp
|
|
into a format of 32-bit integer array,
|
|
specified by
|
|
.Fa bitfield
|
|
and length in bytes by
|
|
.Fa len .
|
|
An integers is in the host byte-order and represents a bit field.
|
|
The first bit at index zero represents CPU number 0, and so on.
|
|
.El
|
|
.Sh CODE REFERENCES
|
|
The
|
|
.Nm
|
|
subsystem is implemented within
|
|
.Pa sys/kern/subr_kcpuset.c .
|
|
.Sh SEE ALSO
|
|
.Xr cpuset 3
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
subsystem first appeared in
|
|
.Nx 6.0 .
|