Difference between revisions of "Fairsched API"
(added Category: Kernel) |
m (Reverted edits by GenieReddicks (Talk) to last revision by Kir) |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
| − | There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a | + | There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a CT. Usually one sets these parameters with the aid of the <code>vzctl</code> utility. But sometimes it can be useful to modify these parameters directly, without using <code>vzctl</code>. For example, it can be required by developers who want to implement an in-place solution to control a particular virtualization system based on OpenVZ. That is why the Fairsched API is introduced. |
The '''Fairsched API''' is the set of system calls that can be used (and that are, in fact, used in the <code>vzctl</code> utility) for altering various parameters of the [[CPU Fair scheduler]], such as <code>cpuunits</code>, <code>cpulimit</code>, <code>cpus</code>, and <code>cpumask</code>. The article is targeted at describing the API. | The '''Fairsched API''' is the set of system calls that can be used (and that are, in fact, used in the <code>vzctl</code> utility) for altering various parameters of the [[CPU Fair scheduler]], such as <code>cpuunits</code>, <code>cpulimit</code>, <code>cpus</code>, and <code>cpumask</code>. The article is targeted at describing the API. | ||
| Line 5: | Line 5: | ||
== CPU weight == | == CPU weight == | ||
| − | + | === Synopsis === | |
<source lang="c"> | <source lang="c"> | ||
| Line 11: | Line 11: | ||
</source> | </source> | ||
| − | + | === Description === | |
| − | The CPU weight defines how much CPU time a | + | The CPU weight defines how much CPU time a CT gets. The smaller the weight is, the more CPU time the container gets. The CPU weight is a relative parameter. That means that multiplying the weight of all running CTs by the same value does not change the CPU time distribution. The minimal value of the weight is 1, and the maximal value is <code>FSCHWEIGHT_MAX</code> (65535). The weight of a newly created CT is set to 500 by default. |
| − | The <code>fairsched_chwt()</code> system call sets the CPU weight of a | + | The <code>fairsched_chwt()</code> system call sets the CPU weight of a CT. <code>id</code> is the id of the CT. <code>wght</code> is the desired weight. |
| − | + | === Return value === | |
On success, <code>fairsched_chwt()</code> returns 0. On error, -1 is returned, and <code>errno</code> is set appropriately. | On success, <code>fairsched_chwt()</code> returns 0. On error, -1 is returned, and <code>errno</code> is set appropriately. | ||
| − | + | === Errors === | |
* <code>EINVAL</code>: <code>id</code>=0. | * <code>EINVAL</code>: <code>id</code>=0. | ||
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range. | * <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range. | ||
| − | * <code>ENOENT</code>: the | + | * <code>ENOENT</code>: the CT does not exist. |
| − | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the | + | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the CT. |
| − | + | === Notes === | |
It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647). | It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647). | ||
| Line 35: | Line 35: | ||
''cpuweight = 500000 / cpuunits'' | ''cpuweight = 500000 / cpuunits'' | ||
| − | |||
== CPU limit == | == CPU limit == | ||
| − | + | === Synopsis === | |
<source lang="c"> | <source lang="c"> | ||
| Line 45: | Line 44: | ||
</source> | </source> | ||
| − | + | === Description === | |
| − | The CPU limit is the upper bound to the CPU usage for a | + | The CPU limit is the upper bound to the CPU usage for a CT. The limit is set for all CPUs the CT can execute on. That means the maximal value of the CPU limit (i.e. no limit) is the maximal limit on 1 CPU, which equals 1024, multiplied by NUM_CPUS, the number of CPUs this VM can execute on. The CPU limit is an absolute parameter in the sense that altering the limit of one CT does not affect the limits of other CTs. |
| − | The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a | + | The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a CT. <code>id</code> is the id of the CT. <code>op</code> can be one of the following: |
* <code>FAIRSCHED_SET_RATE</code> to set the limit; in this case <code>rate</code> is the limit value to set. | * <code>FAIRSCHED_SET_RATE</code> to set the limit; in this case <code>rate</code> is the limit value to set. | ||
| Line 55: | Line 54: | ||
* <code>FAIRSCHED_GET_RATE</code> to get the current value of the limit; the function returns the limit value, <code>rate</code> is not used. | * <code>FAIRSCHED_GET_RATE</code> to get the current value of the limit; the function returns the limit value, <code>rate</code> is not used. | ||
| − | + | === Return value === | |
On success, <code>fairsched_rate()</code> returns the current value of the CPU limit if <code>op</code> is <code>FAIRSCHED_SET_RATE</code> or <code>FAIRSCHED_GET_RATE</code>, or 0 if <code>op</code> is <code>FAIRSCHED_DROP_RATE</code>. On error, -1 is returned, and <code>errno</code> is set appropriately. | On success, <code>fairsched_rate()</code> returns the current value of the CPU limit if <code>op</code> is <code>FAIRSCHED_SET_RATE</code> or <code>FAIRSCHED_GET_RATE</code>, or 0 if <code>op</code> is <code>FAIRSCHED_DROP_RATE</code>. On error, -1 is returned, and <code>errno</code> is set appropriately. | ||
| − | + | === Errors === | |
* <code>EINVAL</code>: <code>id</code>=0. | * <code>EINVAL</code>: <code>id</code>=0. | ||
* <code>EINVAL</code>: <code>op</code> is invalid. | * <code>EINVAL</code>: <code>op</code> is invalid. | ||
* <code>EINVAL</code>: <code>op</code>=<code>FAIRSCHED_SET_RATE</code>, and <code>rate</code><=0. | * <code>EINVAL</code>: <code>op</code>=<code>FAIRSCHED_SET_RATE</code>, and <code>rate</code><=0. | ||
| − | * <code>ENOENT</code>: the | + | * <code>ENOENT</code>: the CT does not exist. |
* <code>ENODATA</code>: <code>op</code>=<code>FAIRSCHED_GET_RATE</code>, and the limit is not set (or was dropped). | * <code>ENODATA</code>: <code>op</code>=<code>FAIRSCHED_GET_RATE</code>, and the limit is not set (or was dropped). | ||
| − | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the | + | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the CT. |
| − | + | === Notes === | |
It is possible to limit the CPU usage of the host system. The host system's id equals <code>INT_MAX</code> (2147483647). | It is possible to limit the CPU usage of the host system. The host system's id equals <code>INT_MAX</code> (2147483647). | ||
| − | CPU limits are available only in | + | CPU limits are available only in RHEL5-based and RHEL6-based kernels, and they behave a bit differently in them in respect of distributing CPU time among CPUs the CT can execute on. |
| − | In the | + | In the RHEL5 kernel the limit has a container-wide meaning. For example, if there are 2 CPUs available for a container, and the limit is set to 1024 (of 2048), the container's CPU usage can be 100/0%, or 50/50%, or any other values whose sum does not exceed 100%. |
| − | In the | + | In the RHEL6 kernel the limit is divided between the CPUs proportionally, and a busy CPU cannot borrow time from an idle one, i.e. with a 2 CPUs container and 1024 (of 2048) limit set the usage of each CPU cannot exceed 50% in any case. |
| − | |||
| − | |||
| + | As a result, the minimal value for the limit is 1 in the RHEL5 kernel and 1 * NUM_CPUS in the RHEL6 kernel. If the given limit is out of the allowed range it is automatically clamped to the range. | ||
== Number of CPUs == | == Number of CPUs == | ||
| − | + | === Synopsis === | |
<source lang="c"> | <source lang="c"> | ||
| Line 89: | Line 87: | ||
</source> | </source> | ||
| − | + | === Description === | |
| − | The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a | + | The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a CT. <code>id</code> is the id of the CT. <code>vcpus</code> is the number of virtual CPUs to set for the CT. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the CT to the number of online CPUs. |
| − | + | === Return value === | |
On success, <code>fairsched_vcpus()</code> returns 0. On error, -1 is returned, and <code>errno</code> is set appropriately. | On success, <code>fairsched_vcpus()</code> returns 0. On error, -1 is returned, and <code>errno</code> is set appropriately. | ||
| − | + | === Errors === | |
* <code>EINVAL</code>: <code>id</code>=0. | * <code>EINVAL</code>: <code>id</code>=0. | ||
| − | * <code>ENOENT</code>: the | + | * <code>ENOENT</code>: the CT does not exist. |
| − | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the | + | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the CT. |
| − | |||
| − | |||
| − | + | === Notes === | |
| + | The parameter have not been implemented in the RHEL6 kernel yet. | ||
== CPU affinity mask == | == CPU affinity mask == | ||
| − | + | === Synopsis === | |
<source lang="c"> | <source lang="c"> | ||
| − | int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask) | + | int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask); |
</source> | </source> | ||
| − | + | === Description === | |
| − | A | + | A CT's CPU affinity mask determines the set of CPUs on which it is eligible to run. A CPU affinity mask is represented by an array of <code>long</code>s so that a CT is allowed to execute on the n-th CPU if and only if the (<code>n%sizeof(long)</code>)-th bit of the (<code>n/sizeof(long)</code>)-th element of the array is set. |
| − | The <code>fairsched_cpumask()</code> system call sets the CPU affinity mask for a | + | The <code>fairsched_cpumask()</code> system call sets the CPU affinity mask for a CT. <code>id</code> is the id of the CT. <code>mask</code> is the mask, and <code>len</code> is the size of the mask, in bytes. |
| − | + | === Return value === | |
On success, <code>fairsched_cpumask()</code> returns 0. On error, -1 is returned, and <code>errno</code> is set appropriately. | On success, <code>fairsched_cpumask()</code> returns 0. On error, -1 is returned, and <code>errno</code> is set appropriately. | ||
| − | + | === Errors === | |
| − | * <code>EBUSY</code>: the | + | * <code>EBUSY</code>: the CT has a child cpuset which is not a subset of the mask. |
* <code>EINVAL</code>: <code>id</code>=0. | * <code>EINVAL</code>: <code>id</code>=0. | ||
| − | * <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the | + | * <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the CT's cpuset is marked exclusive. |
| − | * <code>ENOENT</code>: the | + | * <code>ENOENT</code>: the CT does not exist. |
* <code>ENOMEM</code>: there is no memory to copy the mask. | * <code>ENOMEM</code>: there is no memory to copy the mask. | ||
* <code>ENOSPC</code>: the mask has no active CPUs set. | * <code>ENOSPC</code>: the mask has no active CPUs set. | ||
| − | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the | + | * <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the CT. |
| − | + | === Notes === | |
| − | The parameter is available since the rhel6 kernel. | + | The parameter is available since the [[Download/kernel/rhel6|RHEL6]] kernel. |
[[Category: Kernel]] | [[Category: Kernel]] | ||
| + | [[Category: Resource management]] | ||
Latest revision as of 10:24, 29 March 2011
There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a CT. Usually one sets these parameters with the aid of the vzctl utility. But sometimes it can be useful to modify these parameters directly, without using vzctl. For example, it can be required by developers who want to implement an in-place solution to control a particular virtualization system based on OpenVZ. That is why the Fairsched API is introduced.
The Fairsched API is the set of system calls that can be used (and that are, in fact, used in the vzctl utility) for altering various parameters of the CPU Fair scheduler, such as cpuunits, cpulimit, cpus, and cpumask. The article is targeted at describing the API.
CPU weight[edit]
Synopsis[edit]
int fairsched_chwt(unsigned int id, unsigned int wght);Description[edit]
The CPU weight defines how much CPU time a CT gets. The smaller the weight is, the more CPU time the container gets. The CPU weight is a relative parameter. That means that multiplying the weight of all running CTs by the same value does not change the CPU time distribution. The minimal value of the weight is 1, and the maximal value is FSCHWEIGHT_MAX (65535). The weight of a newly created CT is set to 500 by default.
The fairsched_chwt() system call sets the CPU weight of a CT. id is the id of the CT. wght is the desired weight.
Return value[edit]
On success, fairsched_chwt() returns 0. On error, -1 is returned, and errno is set appropriately.
Errors[edit]
EINVAL:id=0.EINVAL: the value ofwghtis out of the allowed range.ENOENT: the CT does not exist.EPERM: the caller does not have permissions to modify the CPU parameters of the CT.
Notes[edit]
It is possible to change the CPU weight of the host system. The host system's id equals INT_MAX (2147483647).
The cpuunits option of the vzctl utility is not the same thing as the CPU weight described above, but they are closely connected by the simple equation:
cpuweight = 500000 / cpuunits
CPU limit[edit]
Synopsis[edit]
int fairsched_rate(unsigned int id, int op, unsigned int rate);Description[edit]
The CPU limit is the upper bound to the CPU usage for a CT. The limit is set for all CPUs the CT can execute on. That means the maximal value of the CPU limit (i.e. no limit) is the maximal limit on 1 CPU, which equals 1024, multiplied by NUM_CPUS, the number of CPUs this VM can execute on. The CPU limit is an absolute parameter in the sense that altering the limit of one CT does not affect the limits of other CTs.
The fairsched_rate() system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a CT. id is the id of the CT. op can be one of the following:
FAIRSCHED_SET_RATEto set the limit; in this caserateis the limit value to set.FAIRSCHED_DROP_RATEto drop the limit;rateis not used.FAIRSCHED_GET_RATEto get the current value of the limit; the function returns the limit value,rateis not used.
Return value[edit]
On success, fairsched_rate() returns the current value of the CPU limit if op is FAIRSCHED_SET_RATE or FAIRSCHED_GET_RATE, or 0 if op is FAIRSCHED_DROP_RATE. On error, -1 is returned, and errno is set appropriately.
Errors[edit]
EINVAL:id=0.EINVAL:opis invalid.EINVAL:op=FAIRSCHED_SET_RATE, andrate<=0.ENOENT: the CT does not exist.ENODATA:op=FAIRSCHED_GET_RATE, and the limit is not set (or was dropped).EPERM: the caller does not have permissions to modify the CPU parameters of the CT.
Notes[edit]
It is possible to limit the CPU usage of the host system. The host system's id equals INT_MAX (2147483647).
CPU limits are available only in RHEL5-based and RHEL6-based kernels, and they behave a bit differently in them in respect of distributing CPU time among CPUs the CT can execute on.
In the RHEL5 kernel the limit has a container-wide meaning. For example, if there are 2 CPUs available for a container, and the limit is set to 1024 (of 2048), the container's CPU usage can be 100/0%, or 50/50%, or any other values whose sum does not exceed 100%.
In the RHEL6 kernel the limit is divided between the CPUs proportionally, and a busy CPU cannot borrow time from an idle one, i.e. with a 2 CPUs container and 1024 (of 2048) limit set the usage of each CPU cannot exceed 50% in any case.
As a result, the minimal value for the limit is 1 in the RHEL5 kernel and 1 * NUM_CPUS in the RHEL6 kernel. If the given limit is out of the allowed range it is automatically clamped to the range.
Number of CPUs[edit]
Synopsis[edit]
int fairsched_vcpus(unsigned int id, unsigned int vcpus);Description[edit]
The fairsched_vcpus() system call sets the number of virtual CPUs available in a CT. id is the id of the CT. vcpus is the number of virtual CPUs to set for the CT. If vcpus=0, the call attempts to set the number of CPUs in the CT to the number of online CPUs.
Return value[edit]
On success, fairsched_vcpus() returns 0. On error, -1 is returned, and errno is set appropriately.
Errors[edit]
EINVAL:id=0.ENOENT: the CT does not exist.EPERM: the caller does not have permissions to modify the CPU parameters of the CT.
Notes[edit]
The parameter have not been implemented in the RHEL6 kernel yet.
CPU affinity mask[edit]
Synopsis[edit]
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask);Description[edit]
A CT's CPU affinity mask determines the set of CPUs on which it is eligible to run. A CPU affinity mask is represented by an array of longs so that a CT is allowed to execute on the n-th CPU if and only if the (n%sizeof(long))-th bit of the (n/sizeof(long))-th element of the array is set.
The fairsched_cpumask() system call sets the CPU affinity mask for a CT. id is the id of the CT. mask is the mask, and len is the size of the mask, in bytes.
Return value[edit]
On success, fairsched_cpumask() returns 0. On error, -1 is returned, and errno is set appropriately.
Errors[edit]
EBUSY: the CT has a child cpuset which is not a subset of the mask.EINVAL:id=0.EINVAL: the mask intersects with a cpuset, and either that cpuset or the CT's cpuset is marked exclusive.ENOENT: the CT does not exist.ENOMEM: there is no memory to copy the mask.ENOSPC: the mask has no active CPUs set.EPERM: the caller does not have permissions to modify the CPU parameters of the CT.
Notes[edit]
The parameter is available since the RHEL6 kernel.
