CPU_AND_ATOMIC (9)

Leading comments

Copyright (c) 2015 Conrad Meyer <cem@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
   document...

(The comments found at the beginning of the groff file "man9/CPU_AND_ATOMIC.9freebsd".)

NAME

cpuset(9) --- CPUSET_T_INITIALIZER CPUSET_FSET CPU_CLR CPU_COPY CPU_ISSET CPU_SET CPU_ZERO CPU_FILL CPU_SETOF CPU_EMPTY CPU_ISFULLSET CPU_FFS CPU_COUNT CPU_SUBSET CPU_OVERLAP CPU_CMP CPU_OR CPU_AND CPU_NAND CPU_CLR_ATOMIC CPU_SET_ATOMIC CPU_SET_ATOMIC_ACQ CPU_AND_ATOMIC CPU_OR_ATOMIC CPU_COPY_STORE_REL - cpuset manipulation macros

SYNOPSIS

In sys/_cpuset.h In sys/cpuset.h Fn CPUSET_T_INITIALIZER ARRAY_CONTENTS Vt CPUSET_FSET Fn CPU_CLR size_t cpu_idx cpuset_t *cpuset Fn CPU_COPY cpuset_t *from cpuset_t *to Ft bool Fn CPU_ISSET size_t cpu_idx cpuset_t *cpuset Fn CPU_SET size_t cpu_idx cpuset_t *cpuset Fn CPU_ZERO cpuset_t *cpuset Fn CPU_FILL cpuset_t *cpuset Fn CPU_SETOF size_t cpu_idx cpuset_t *cpuset Ft bool Fn CPU_EMPTY cpuset_t *cpuset Ft bool Fn CPU_ISFULLSET cpuset_t *cpuset Ft int Fn CPU_FFS cpuset_t *cpuset Ft int Fn CPU_COUNT cpuset_t *cpuset Ft bool Fn CPU_SUBSET cpuset_t *haystack cpuset_t *needle Ft bool Fn CPU_OVERLAP cpuset_t *cpuset1 cpuset_t *cpuset2 Ft bool Fn CPU_CMP cpuset_t *cpuset1 cpuset_t *cpuset2 Fn CPU_OR cpuset_t *dst cpuset_t *src Fn CPU_AND cpuset_t *dst cpuset_t *src Fn CPU_NAND cpuset_t *dst cpuset_t *src Fn CPU_CLR_ATOMIC size_t cpu_idx cpuset_t *cpuset Fn CPU_SET_ATOMIC size_t cpu_idx cpuset_t *cpuset Fn CPU_SET_ATOMIC_ACQ size_t cpu_idx cpuset_t *cpuset Fn CPU_AND_ATOMIC cpuset_t *dst cpuset_t *src Fn CPU_OR_ATOMIC cpuset_t *dst cpuset_t *src Fn CPU_COPY_STORE_REL cpuset_t *from cpuset_t *to

DESCRIPTION

The family of macros provide a flexible and efficient CPU set implementation, backed by the bitset(9) macros. Each CPU is represented by a single bit. The maximum number of CPUs representable by Vt cpuset_t is MAXCPU Individual CPUs in cpusets are referenced with indices zero through Fa MAXCPU - 1 .

The Fn CPUSET_T_INITIALIZER macro allows one to initialize a Vt cpuset_t with a compile time literal value.

The Fn CPUSET_FSET macro defines a compile time literal, usable by Fn CPUSET_T_INITIALIZER , representing a full cpuset (all CPUs present). For examples of Fn CPUSET_T_INITIALIZER and Fn CPUSET_FSET usage, see the Sx CPUSET_T_INITIALIZER EXAMPLE section.

The Fn CPU_CLR macro removes CPU Fa cpu_idx from the cpuset pointed to by Fa cpuset . The Fn CPU_CLR_ATOMIC macro is identical, but the bit representing the CPU is cleared with atomic machine instructions.

The Fn CPU_COPY macro copies the contents of the cpuset Fa from to the cpuset Fa to . Fn CPU_COPY_STORE_REL is similar, but copies component machine words from Fa from and writes them to Fa to with atomic store with release semantics. (That is, if Fa to is composed of multiple machine words, Fn CPU_COPY_STORE_REL performs multiple individually atomic operations.)

The Fn CPU_SET macro adds CPU Fa cpu_idx to the cpuset pointed to by Fa cpuset , if it is not already present. The Fn CPU_SET_ATOMIC macro is identical, but the bit representing the CPU is set with atomic machine instructions. The Fn CPU_SET_ATOMIC_ACQ macro sets the bit representing the CPU with atomic acquire semantics.

The Fn CPU_ZERO macro removes all CPUs from Fa cpuset .

The Fn CPU_FILL macro adds all CPUs to Fa cpuset .

The Fn CPU_SETOF macro removes all CPUs in Fa cpuset before adding only CPU Fa cpu_idx .

The Fn CPU_EMPTY macro returns true if Fa cpuset is empty.

The Fn CPU_ISFULLSET macro returns true if Fa cpuset is full (the set of all CPUs).

The Fn CPU_FFS macro returns the 1-index of the first (lowest) CPU in Fa cpuset , or zero if Fa cpuset is empty. Like with ffs(3), to use the non-zero result of Fn CPU_FFS as a Fa cpu_idx index parameter to any other macro, you must subtract one from the result.

The Fn CPU_COUNT macro returns the total number of CPUs in Fa cpuset .

The Fn CPU_SUBSET macro returns true if Fa needle is a subset of Fa haystack .

The Fn CPU_OVERLAP macro returns true if Fa cpuset1 and Fa cpuset2 have any common CPUs. (That is, if Fa cpuset1 AND Fa cpuset2 is not the empty set.)

The Fn CPU_CMP macro returns true if Fa cpuset1 is NOT equal to Fa cpuset2 .

The Fn CPU_OR macro adds CPUs present in Fa src to Fa dst . (It is the equivalent of the scalar: Fa dst |= Fa src . ) Fn CPU_OR_ATOMIC is similar, but sets the bits representing CPUs in the component machine words in Fa dst with atomic machine instructions. (That is, if Fa dst is composed of multiple machine words, Fn CPU_OR_ATOMIC performs multiple individually atomic operations.)

The Fn CPU_AND macro removes CPUs absent from Fa src from Fa dst . (It is the equivalent of the scalar: Fa dst &= Fa src . ) Fn CPU_AND_ATOMIC is similar, with the same atomic semantics as Fn CPU_OR_ATOMIC .

The Fn CPU_NAND macro removes CPUs in Fa src from Fa dst . (It is the equivalent of the scalar: Fa dst &= Fa ~ src . )

CPUSET_T_INITIALIZER EXAMPLE

cpuset_t myset;

/* Initialize myset to filled (all CPUs) */
myset = CPUSET_T_INITIALIZER(CPUSET_FSET);

/* Initialize myset to only the lowest CPU */
myset = CPUSET_T_INITIALIZER(0x1);

SEE ALSO

cpuset(1), cpuset(2), bitset(9)

HISTORY

In sys/cpuset.h first appeared in Fx 7.1 , released in January 2009, and in Fx 8.0 , released in November 2009.

This manual page first appeared in Fx 11.0 .

AUTHORS

An -nosplit The macros were written by An Jeff Roberson Aq Mt jeff@FreeBSD.org . This manual page was written by An Conrad Meyer Aq Mt cem@FreeBSD.org .

CAVEATS

Unlike every other reference to individual set members, which are zero-indexed, Fn CPU_FFS returns a one-indexed result (or zero if the cpuset is empty).