cpuset(5) cpuset(5) NAME cpuset - 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 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. 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 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 cpuset cpusetAttach(3x) Attach the current process to a cpuset cpusetAttachPID(3x) Attach a specific process to a cpuset cpusetDetachAll(3x) Detach all threads from a cpuset cpusetDetachPID Detach a specific process from a cpuset cpusetDestroy(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 cpuset cpusetGetName(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 cpuset cpusetGetProperties(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. #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)) { 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 \ 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 ALSO 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), IRIX Admin: Resource Administration Page 6