cpuset(5)cpuset(5)NAMEcpuset - overview of cpusets
DESCRIPTION
A cpuset is a named set of CPUs, which may be defined to be restricted or
open. A restricted cpuset only allows processes that are members of the
cpuset to run on the set of CPUs. An open cpuset allows any process to
run on its cpus, but a process that is a member of the cpuset can only
run on the CPUs belonging to the cpuset.
A principal use of cpusets is to create a partition of CPUs within a
larger system. By doing this, a set of processes can be contained to
specific CPUs, reducing the amount of interaction those processes have
with other work on the system. In the case of a restricted cpuset, the
processes that are attached to that cpuset will not be affected by other
work on the system; only those processes attached to the cpuset can be
scheduled to run on the CPUs assigned to the cpuset. An open cpuset can
be used to restrict processes to a set of CPUs so that the affect these
processes have on the rest of the system is minimized.
There are currently two methods in which to use cpusets: the cpuset(1)
command, and the cpuset library (see THE CPUSET LIBRARY section below).
For information on how to use cpusets in a Trusted IRIX environment, see
the cpuset(1) man page.
THE CPUSET COMMAND
The cpuset command is used to create and destroy cpusets, to retrieve
information about existing cpusets, and to attach a process and all of
its children to a cpuset.
The cpuset command uses a cpuset configuration file and a name (see
cpuset(4) for a definition of the file format). The cpuset configuration
file is used to define the CPUs that are members of the cpuset. It also
contains additional parameters required to define the cpuset. A cpuset
name is between three and eight characters long; names of two or less
characters are reserved.
The file permissions of the configuration file define access to the
cpuset. When permissions need to be checked, the current permissions of
the file are used. It is therefore possible to change access to a
particular cpuset without having to tear it down and recreate it, simply
by changing the access permissions. Read access allows a user to
retrieve information about a cpuset while execute permission allows the
user to attach a process to the cpuset.
Volatile cpusets are cpusets that can be created by users without the
CAP_SCHED_MGT capability. The system administrator can load into the
system a description of the nodes that can be used with the cpuset-L
command. After that users may create their own cpusets as long as they
only use resources within the nodes specified by the administrator.
Page 1
cpuset(5)cpuset(5)
Volatile cpusets are useful for situations where cpusets are needed in a
non-batch environment. The configuration files are the same as those
used in creating other cpusets. As soon as all the processes and threads
in a volatile cpuset exit, IRIX will destroy the cpuset. If the threads
are moved to another cpuset or there are other problems, the cpuset will
not be destroyed. If this situation occurs the cpuset will need to be
manually destroyed and an error message may be placed in the system log.
For additional information concerning the cpuset command, consult the
cpuset(1) manual page.
THE CPUSET LIBRARY
The cpuset library provides interfaces that allow a programmer to create
and destroy cpusets, retrieve information about existing cpusets, to
attach a process and all of its children to a cpuset, and to attach or
detach a specific process identified by its PID to or from a cpuset.
The cpuset library requires that a permission file be defined for a
cpuset that is created. The permissions file may be an empty file, since
it is only the file permissions for the file that define access to the
cpuset. When permissions need to be checked, the current permissions of
the file are used. It is therefore possible to change access to a
particular cpuset without having to tear it down and recreate it, simply
by changing the access permissions. Read access allows a user to
retrieve information about a cpuset while execute permission allows the
user to attach a process to the cpuset.
The cpuset library is provided as a N32 DSO library. The library file is
libcpuset.so, and it is normally located in the directory /lib32. Users
of the library must include the cpuset.h header file which is located in
/usr/include. The function interfaces provided in the cpuset library are
declared as optional interfaces to allow for backwards compatibility as
new interfaces are added to the library. This library is only available
on IRIX 6.5.8 and later versions.
It is possible to compile and run a program that uses this DSO and its
interfaces if they are available, but continues to execute if they are
missing. To do this, a replacement library for libcpuset.so must be
created. An example of how to create a replacement library is provided
in the EXAMPLES section.
The function interfaces within the cpuset library include:
cpusetCreate(3x)
Create a cpusetcpusetAttach(3x)
Attach the current process to a cpusetcpusetAttachPID(3x)
Attach a specific process to a cpuset
Page 2
cpuset(5)cpuset(5)cpusetDetachAll(3x)
Detach all threads from a cpuset
cpusetDetachPID
Detach a specific process from a cpusetcpusetDestroy(3x)
Destroy a cpuset
cpusetLoad((3x)
cpusetGetCPUCount(3x)
Obtain the number of CPUs configured on the system
cpusetGetCPUList(3x)
Get the list of all CPUs assigned to a cpusetcpusetGetName(3x)
Get the name of the cpuset to which a process is attached
cpusetGetNameList(3x)
Get a list names for all defined cpusets
cpusetGetPIDList(3x)
Get a list of all PIDs attached to a cpusetcpusetGetProperties(3x)
Get various properties of an existing cpuset.
cpusetAllocQueueDef(3x)
Allocate a cpuset_QueueDef_t structure
cpusetFreeProperties(3x)
Release memory used by a cpuset_Properties_t structure
cpusetFreeQueueDef(3x)
Release memory used by a cpuset_QueueDef_t structure
cpusetFreeCPUList(3x)
Release memory used by a cpuset_CPUList_t structure
cpusetFreeNameList(3x)
Release memory used by a cpuset_NameList_t structure
cpusetFreePIDList(3x)
Release memory used by a cpuset_PIDList_t structure
EXAMPLES
This example creates a cpuset named "myqueue" containing CPUs 4, 8, and
12. The example uses the interfaces in the cpuset library,
/lib32/libcpuset.so, if they are present. If the interfaces are not
present, it attempts to use the cpuset(1) command to create the cpuset.
Page 3
cpuset(5)cpuset(5)
#include <cpuset.h>
#include <stdio.h>
#include <errno.h>
#define PERMFILE "/usr/tmp/permfile"
int
main(int argc, char **argv)
{
cpuset_QueueDef_t *qdef;
char *qname = "myqueue";
FILE *fp;
/* Alloc queue def for 3 CPU IDs */
if (_MIPS_SYMBOL_PRESENT(cpusetAllocQueueDef)) {
printf("Creating cpuset definition\n");
qdef = cpusetAllocQueueDef(3);
if (!qdef) {
perror("cpusetAllocQueueDef");
exit(1);
}
/* Define attributes of the cpuset */
qdef->flags = CPUSET_CPU_EXCLUSIVE
| CPUSET_MEMORY_LOCAL
| CPUSET_MEMORY_EXCLUSIVE;
qdef->permfile = PERMFILE;
qdef->cpu->count = 3;
qdef->cpu->list[0] = 4;
qdef->cpu->list[1] = 8;
qdef->cpu->list[2] = 12;
} else {
printf("Writing cpuset command config"
" info into %s\n", PERMFILE);
fp = fopen(PERMFILE, "a");
if (!fp) {
perror("fopen");
exit(1);
}
fprintf(fp, "EXCLUSIVE\n");
fprintf(fp, "MEMORY_LOCAL\n");
fprintf(fp, "MEMORY_EXCLUSIVE\n\n");
fprintf(fp, "CPU 4\n");
fprintf(fp, "CPU 8\n");
fprintf(fp, "CPU 12\n");
fclose(fp);
}
/* Request that the cpuset be created */
if (_MIPS_SYMBOL_PRESENT(cpusetCreate)) {
printf("Creating cpuset = %s\n", qname);
if (!cpusetCreate(qname, qdef)) {
Page 4
cpuset(5)cpuset(5)
perror("cpusetCreate");
exit(1);
}
} else {
char command[256];
fprintf(command, "/usr/sbin/cpuset -q %s -c"
"-f %s", qname,
PERMFILE);
if (system(command) < 0) {
perror("system");
exit(1);
}
}
/* Free memory for queue def */
if (_MIPS_SYMBOL_PRESENT(cpusetFreeQueueDef)) {
printf("Finished with cpuset definition,"
" releasing memory\n");
cpusetFreeQueueDef(qdef);
}
return 0;
}
This example shows how to create a replacement library for
/lib32/libcpuset.so so that a program built to use the cpuset library
interfaces will execute if the library is not present.
1. The file replace.c is created, and contains the following line of
code:
static void cpusetNULL(void) { }
2. The file replace.c is compiled:
cc -mips3 -n32 -c replace.c
3. The object replace.o created in the previous step is placed in a
library:
ar ccrl libcpuset.a replace.o
4. The library is converted into a DSO:
ld -mips3 -n32 -quickstart_info -nostdlib \
-elf -shared -all -soname libcpuset.so \
-no_unresolved -quickstart_info -set_version \
Page 5
cpuset(5)cpuset(5)
sgi1.0 libcpuset.a -o libcpuset.so
5. The DSO is installed on the system:
install -F /opt/lib32 -m 444 -src libcpuset.so \
libcpuset.so
The replacement library can be installed in a directory defined by the
LD_LIBRARYN32_PATH environment variable (see rld(1)). If the replacement
library must be installed in a directory that is in the default search
path for shared libraries, it should be installed in /opt/lib32.
NOTES
In a cluster environment, the cpuset configuration file should reside on
the root filesystem. If the cpuset configuration file resides on a
filesystem other than the root filesystem and you attempt to unmount the
filesystem, the vnode for the cpuset remains active and the unmount (see
unmount(1M) command fails.
SEE ALSOcpuset(1), cpusetAllocQueueDef(3x), cpusetAttach(3x),
cpusetAttachPID(3x), cpusetCreate(3x), cpusetDestroy(3x),
cpusetDetachAll(3x), cpusetDetachPID(3x), cpusetFreeCPUList(3x),
cpusetFreeNameList(3x), cpusetFreePIDList(3x), cpusetFreeProperties(3x),
cpusetGetCPUCount(3x), cpusetGetCPUList(3x), cpusetGetName(3x),
cpusetGetNameList(3x), cpusetGetPIDList(3x), cpusetGetProperties(3x),
cpuset(4).
IRIX Admin: Resource Administration
Page 6
