OpenVZ Virtuozzo Containers Wiki - User contributions [en]

Fairsched API

2011-01-25T08:46:31Z

Vdavydov:

There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. 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.

== CPU weight ==

'''Synopsis:'''

<source lang="c">
int fairsched_chwt(unsigned int id, unsigned int wght);
</source>

'''Description:'''

The CPU weight defines how much CPU time a VE 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 VEs 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 VE is set to 500 by default.

The <code>fairsched_chwt()</code> system call sets the CPU weight of a VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647).

The <code>cpuunits</code> option of the <code>vzctl</code> 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_rate(unsigned int id, int op, unsigned int rate);
</source>

'''Description:'''

The CPU limit is the upper bound to the CPU usage for a VE. The limit is set for all CPUs the VE 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 VE does not affect the limits of other VEs.

The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a VE. <code>id</code> is the id of the VE. <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_DROP_RATE</code> to drop the limit; <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <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>ENOENT</code>: the VE does not exist.
* <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 VE.

'''Notes:'''

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 rhel5-based and rhel6-based kernels, and they behave a bit differently in them in respect of distributing CPU time among CPUs the VE 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_vcpus(unsigned int id, unsigned int vcpus);
</source>

'''Description:'''

The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a VE. <code>id</code> is the id of the VE. <code>vcpus</code> is the number of virtual CPUs to set for the VE. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the VE 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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

The parameter have not been implemented in the rhel6 kernel yet.

== CPU affinity mask ==

'''Synopsis:'''

<source lang="c">
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask)
</source>

'''Description:'''

A VE'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 VE 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 VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EBUSY</code>: the VE has a child cpuset which is not a subset of the mask.
* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the VE's cpuset is marked exclusive.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENOMEM</code>: there is no memory to copy the mask.
* <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 VE.

'''Notes:'''

The parameter is available since the rhel6 kernel.

Fairsched API

2011-01-25T08:43:43Z

Vdavydov:

There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. 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.

== CPU weight ==

'''Synopsis:'''

<source lang="c">
int fairsched_chwt(unsigned int id, unsigned int wght);
</source>

'''Description:'''

The CPU weight defines how much CPU time a VE 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 VEs 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 VE is set to 500 by default.

The <code>fairsched_chwt()</code> system call sets the CPU weight of a VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647).

The <code>cpuunits</code> option of the <code>vzctl</code> 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_rate(unsigned int id, int op, unsigned int rate);
</source>

'''Description:'''

The CPU limit is the upper bound to the CPU usage for a VE. The limit is set for all CPUs the VE 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 VE does not affect the limits of other VEs.

The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a VE. <code>id</code> is the id of the VE. <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_DROP_RATE</code> to drop the limit; <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <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>ENOENT</code>: the VE does not exist.
* <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 VE.

'''Notes:'''

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 rhel5-based and rhel6-based kernels, and they behave a bit differently in them in respect of distributing the CPU time among CPUs the VE 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 limit value is out of the allowed range it is automatically clamped to the range.

== Number of CPUs ==

'''Synopsis:'''

<source lang="c">
int fairsched_vcpus(unsigned int id, unsigned int vcpus);
</source>

'''Description:'''

The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a VE. <code>id</code> is the id of the VE. <code>vcpus</code> is the number of virtual CPUs to set for the VE. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the VE 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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

The parameter have not been implemented in the rhel6 kernel yet.

== CPU affinity mask ==

'''Synopsis:'''

<source lang="c">
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask)
</source>

'''Description:'''

A VE'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 VE 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 VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EBUSY</code>: the VE has a child cpuset which is not a subset of the mask.
* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the VE's cpuset is marked exclusive.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENOMEM</code>: there is no memory to copy the mask.
* <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 VE.

'''Notes:'''

The parameter is available since the rhel6 kernel.

Fairsched API

2011-01-25T08:34:54Z

Vdavydov:

There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. 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.

== CPU weight ==

'''Synopsis:'''

<source lang="c">
int fairsched_chwt(unsigned int id, unsigned int wght);
</source>

'''Description:'''

The CPU weight defines how much CPU time a VE 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 VEs 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 VE is set to 500 by default.

The <code>fairsched_chwt()</code> system call sets the CPU weight of a VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647).

The <code>cpuunits</code> option of the <code>vzctl</code> 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_rate(unsigned int id, int op, unsigned int rate);
</source>

'''Description:'''

The CPU limit is the upper bound to the CPU usage for a VE. The limit is set for all CPUs the VE 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 the number of CPUs this VM can execute on. The minimal value is 1. The CPU limit is an absolute parameter in the sense that altering the limit of one VE does not affect the limits of other VEs.

The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a VE. <code>id</code> is the id of the VE. <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_DROP_RATE</code> to drop the limit; <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <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>ENOENT</code>: the VE does not exist.
* <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 VE.

'''Notes:'''

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 rhel5-based and rhel6-based kernels, and they behave a bit differently in them in respect of distributing the CPU time among CPUs the VE 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.

== Number of CPUs ==

'''Synopsis:'''

<source lang="c">
int fairsched_vcpus(unsigned int id, unsigned int vcpus);
</source>

'''Description:'''

The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a VE. <code>id</code> is the id of the VE. <code>vcpus</code> is the number of virtual CPUs to set for the VE. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the VE 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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

The parameter have not been implemented in the rhel6 kernel yet.

== CPU affinity mask ==

'''Synopsis:'''

<source lang="c">
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask)
</source>

'''Description:'''

A VE'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 VE 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 VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EBUSY</code>: the VE has a child cpuset which is not a subset of the mask.
* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the VE's cpuset is marked exclusive.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENOMEM</code>: there is no memory to copy the mask.
* <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 VE.

'''Notes:'''

The parameter is available since the rhel6 kernel.

Fairsched API

2011-01-25T07:47:38Z

Vdavydov:

There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. 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.

== CPU weight ==

'''Synopsis:'''

<source lang="c">
int fairsched_chwt(unsigned int id, unsigned int wght);
</source>

'''Description:'''

The CPU weight defines how much CPU time a VE 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 VEs 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 VE is set to 500 by default.

The <code>fairsched_chwt()</code> system call sets the CPU weight of a VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647).

The <code>cpuunits</code> option of the <code>vzctl</code> 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_rate(unsigned int id, int op, unsigned int rate);
</source>

'''Description:'''

The CPU limit is the upper bound to the CPU usage for a VE. The limit is set for all CPUs the VE 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 the number of CPUs this VM can execute on. The minimal value is 1. The CPU limit is an absolute parameter in the sense that altering the limit of one VE does not affect the limits of other VEs.

The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a VE. <code>id</code> is the id of the VE. <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_DROP_RATE</code> to drop the limit; <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: <code>op</code> is invalid.
* <code>EINVAL</code>: <code>op</code>=<code>FAIRSCHED_SET_RATE</code>, and the value of <code>rate</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <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 VE.

'''Notes:'''

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 rhel5-based and rhel6-based kernels, and they behave a bit differently in them in respect of distributing the CPU time among CPUs the VE 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.

== Number of CPUs ==

'''Synopsis:'''

<source lang="c">
int fairsched_vcpus(unsigned int id, unsigned int vcpus);
</source>

'''Description:'''

The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a VE. <code>id</code> is the id of the VE. <code>vcpus</code> is the number of virtual CPUs to set for the VE. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the VE 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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

The parameter have not been implemented in the rhel6 kernel yet.

== CPU affinity mask ==

'''Synopsis:'''

<source lang="c">
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask)
</source>

'''Description:'''

A VE'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 VE 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 VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EBUSY</code>: the VE has a child cpuset which is not a subset of the mask.
* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the VE's cpuset is marked exclusive.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENOMEM</code>: there is no memory to copy the mask.
* <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 VE.

'''Notes:'''

The parameter is available since the rhel6 kernel.

Fairsched API

2011-01-25T06:25:45Z

Vdavydov:

There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. 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.

== CPU weight ==

'''Synopsis:'''

<source lang="c">
int fairsched_chwt(unsigned int id, unsigned int wght);
</source>

'''Description:'''

The CPU weight defines how much CPU time a VE 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 VEs 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 VE is set to 500 by default.

The <code>fairsched_chwt()</code> system call sets the CPU weight of a VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647).

The <code>cpuunits</code> option of the <code>vzctl</code> 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_rate(unsigned int id, int op, unsigned int rate);
</source>

'''Description:'''

The CPU limit is the upper bound to the CPU usage for a VE. The limit is set for all CPUs the VE 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 the number of CPUs this VM can execute on. The minimal value is 1. The CPU limit is an absolute parameter in the sense that altering the limit of one VE does not affect the limits of other VEs.

The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a VE. <code>id</code> is the id of the VE. <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_DROP_RATE</code> to drop the limit; <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: <code>op</code> is invalid.
* <code>EINVAL</code>: <code>op</code>=<code>FAIRSCHED_SET_RATE</code>, and the value of <code>rate</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENODATA</code>: <code>op</code>=<code>FAIRSCHED_SET_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 VE.

'''Notes:'''

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 rhel5-based and rhel6-based kernels, and they behave a bit differently in them in respect of distributing the CPU time among CPUs the VE 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.

== Number of CPUs ==

'''Synopsis:'''

<source lang="c">
int fairsched_vcpus(unsigned int id, unsigned int vcpus);
</source>

'''Description:'''

The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a VE. <code>id</code> is the id of the VE. <code>vcpus</code> is the number of virtual CPUs to set for the VE. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the VE 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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

The parameter have not been implemented in the rhel6 kernel yet.

== CPU affinity mask ==

'''Synopsis:'''

<source lang="c">
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask)
</source>

'''Description:'''

A VE'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 VE 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 VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EBUSY</code>: the VE has a child cpuset which is not a subset of the mask.
* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the VE's cpuset is marked exclusive.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENOMEM</code>: there is no memory to copy the mask.
* <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 VE.

'''Notes:'''

The parameter is available since the rhel6 kernel.

Fairsched API

2011-01-24T16:06:01Z

Vdavydov: Created page with 'There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. Usually one sets these parameters with the aid of the <code>vzctl</code> util…'

There are several parameters tuning which the OpenVZ administrator can change the CPU usage of a VE. 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 to describe the API.

== CPU weight ==

'''Synopsis:'''

<source lang="c">
int fairsched_chwt(unsigned int id, unsigned int wght);
</source>

'''Description:'''

The CPU weight defines how much CPU time a VE 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 VEs 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 VE is set to 500 by default.

The <code>fairsched_chwt()</code> system call sets the CPU weight of a VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the value of <code>wght</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

It is possible to change the CPU weight of the host system. The host system's id equals <code>INT_MAX</code> (2147483647).

The <code>cpuunits</code> option of the <code>vzctl</code> 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 ==

'''Synopsis:'''

<source lang="c">
int fairsched_rate(unsigned int id, int op, unsigned int rate);
</source>

'''Description:'''

The CPU limit is the upper bound to the CPU usage for a VE. The limit is set for all CPUs the VE 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 the number of CPUs this VM can execute on. The minimal value is 1. The CPU limit is an absolute parameter in the sense that altering the limit of one VE does not affect the limits of other VEs.

The <code>fairsched_rate()</code> system call is used to set, get, or drop (i.e. set to the maximum) CPU limit of a VE. <code>id</code> is the id of the VE. <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_DROP_RATE</code> to drop the limit; <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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: <code>op</code> is invalid.
* <code>EINVAL</code>: <code>op</code>=<code>FAIRSCHED_SET_RATE</code>, and the value of <code>rate</code> is out of the allowed range.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENODATA</code>: <code>op</code>=<code>FAIRSCHED_SET_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 VE.

'''Notes:'''

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 rhel5-based and rhel6-based kernels, and they behave a bit differently in them in respect of distributing the CPU time among CPUs the VE 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.

== Number of CPUs ==

'''Synopsis:'''

<source lang="c">
int fairsched_vcpus(unsigned int id, unsigned int vcpus);
</source>

'''Description:'''

The <code>fairsched_vcpus()</code> system call sets the number of virtual CPUs available in a VE. <code>id</code> is the id of the VE. <code>vcpus</code> is the number of virtual CPUs to set for the VE. If <code>vcpus</code>=0, the call attempts to set the number of CPUs in the VE 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.

'''Errors:'''

* <code>EINVAL</code>: <code>id</code>=0.
* <code>ENOENT</code>: the VE does not exist.
* <code>EPERM</code>: the caller does not have permissions to modify the CPU parameters of the VE.

'''Notes:'''

The parameter have not been implemented in the rhel6 kernel yet.

== CPU affinity mask ==

'''Synopsis:'''

<source lang="c">
int fairsched_cpumask(unsigned int id, unsigned int len, unsigned long *mask)
</source>

'''Description:'''

A VE'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 VE 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 VE. <code>id</code> is the id of the VE. <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.

'''Errors:'''

* <code>EBUSY</code>: the VE has a child cpuset which is not a subset of the mask.
* <code>EINVAL</code>: <code>id</code>=0.
* <code>EINVAL</code>: the mask intersects with a cpuset, and either that cpuset or the VE's cpuset is marked exclusive.
* <code>ENOENT</code>: the VE does not exist.
* <code>ENOMEM</code>: there is no memory to copy the mask.
* <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 VE.

'''Notes:'''

The parameter is available since the rhel6 kernel.

Ubstat system call

2011-01-20T14:06:41Z

Vdavydov:

This article describes an interesting system call which was designed to pick beancounters statistics.

== Overview ==
The system call appeared in the very first version of the OpenVZ. Its API is rather sloppy, but this is something we have to live with due to backward compatibility reasons.

The main intention of this system call is to allow a user space process get the beancounters statistics ''periodically''. This statistics includes the fields observed in the <code>/proc/user_beancounters</code> file and one more field - the so called <code>minheld</code> value which is opposite to the <code>maxheld</code> one. As long as exporting the statistics the system call also notifies the task about the desired period has elapsed. The notification is performed by sending a signal to a process and this notification is one-shot.

== How it works ==
The typical usage of this call is in performing the following steps.
# Request the amount of resources
# Get the IDs of all the living beancounters
# Setup a handler for some signal (e.g. USR1)
# Perform a system call to setup the notification
# Go do something (or sleep for ever)

In a signal handler one should just perform a respective system call to get the stats and schedule the next notification (yes, they are performed in one go; see below for more details).

== API ==
The system call description is

<source lang="c">
long ubstat(int func, unsigned long luid, void *notif, void *buf, int size);
</source>

The macros and data typed used are declared in <code>include/ub/ub_stat.h</code> file.

=== Arguments description ===

'''<code>func</code>''' is like <code>cmd</code> in the <code>ioctl</code> system call. It can be one of
* <code>UBSTAT_READ_ONE</code> to read basic stats for one resource. The desired resource itself should be <code>or</code>-ed with the <code>func</code>
* <code>UBSTAT_READ_ALL</code> to read basic stats about all the resources
* <code>UBSTAT_READ_FULL</code> to read extended stats about all the resources
* <code>UBSTAT_UBLIST</code> to get the ids of the beancounters
* <code>UBSTAT_UBPARMNUM</code> to get the number of resources used by the kernel
* <code>UBSTAT_GETTIME</code>

See below for what ''basic'' and ''extended'' stats mean.

'''<code>luid</code>''' is the desired beancounter ID. Only one beancounter can be checked at one call.

'''<code>notif</code>''' is the pointer to a <code>ubnotifrq_t</code> structure which describes the notification details (see below).

'''<code>buf</code>''' is the pointer to a chunk of memory, which will contain the data requested.

'''<code>size</code>''' is the <code>buf</code> memory size.

=== The statistics format ===
The format of data returned into the buffer depends on the function requested.

'''1. <code>UBSTAT_READ_ONE</code>''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

typedef struct {
unsigned long maxheld;
unsigned long failcnt;
} ubstatparm_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[1];
}
</source>

It contains the time period for which the stats are returned and the <code>maxheld</code> and <code>failcnt</code> for the resource.

'''2. <code>UBSTAT_READ_ALL</code>''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

typedef struct {
unsigned long maxheld;
unsigned long failcnt;
} ubstatparm_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[UB_RESOURCES];
}
</source>

It contains the same info as the <code>UBSTAT_READ_ONE</code> does, but for all the resources.

'''3. <code>UBSTAT_READ_FULL</code>''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

typedef struct {
unsigned long barrier;
unsigned long limit;
unsigned long held;
unsigned long maxheld;
unsigned long minheld;
unsigned long failcnt;
unsigned long __unused1;
unsigned long __unused2;
} ubstatparmf_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparmf_t param[UB_RESOURCES];
}
</source>

It contains the extended info for all the resources.

'''4. UBSTAT_UBLIST''' treats the <code>buf</code> to point to the <code>unsigned long</code> array.

'''5. UBSTAT_UBPARMNUM''' ignores the <code>buf</code>.

'''6. UBSTAT_GETTIME''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstattime_t cur_time;
};
</source>

It returns the time interval within which the stats are collected and the current time.

All the times used are in seconds.

=== Notification ===
The notification info is passed via the <code>notif</code> argument and is being set up for all the functions except the <code>UBLIST</code> and the <code>UBPARNUM</code>. The notification is one-shot, but note that once you requested the statistics the next shot is scheduled at the same time.

The <code>notif</code> should point to
<source lang="c">
typedef struct {
long maxinterval;
int signum;
} ubnotifrq_t;
</source>

The <code>maxinterval</code> is the time after which the notification will be delivered. It should be more than 1 (second).

The <code>signum</code> is the signal that will be sent to notify.

=== Return value ===
The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code> it returns <code>UB_RESOURCES</code> and in all other cases it returns the amount of bytes written to the <code>buf</code>.

== Demo ==
The following program demonstrates how you can (but not should) use the described API. This example is deliberately made very stupid and simple to demonstrate the main idea and will only work on x86_64.
<source lang="c">
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <ub_stat.h>
#include <signal.h>

#define UBSTAT_BUFSIZE 4096
#define UBSTAT_NOTIFSIG SIGUSR1
#define UB_RESOURCES 24

static char ubstat_buf[UBSTAT_BUFSIZE];
static int luid, func;
static ubnotifrq_t notif;
static void (*print_stat)(void *buf);

#define sys_ubstat(args...) syscall(503, ## args)

static void usage(void)
{
printf("ubstat <id> <period> <resource>\n");
printf("resource can be either num or:\n");
printf("-1 for all maxheld and failcnt\n");
printf("-2 for all at all\n");
}

static void print_stat_one(void *buf)
{
struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[1];
} *data;

data = buf;

printf("maxheld: %lu\n", data->param[0].maxheld);
printf("failcnt: %lu\n", data->param[0].failcnt);
}

static void print_stat_all(void *buf)
{
struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[UB_RESOURCES];
} *data;
int res;

data = buf;
for (res = 0; res < UB_RESOURCES; res++) {
printf("res %d\n", res);
printf("\tmaxheld: %lu\n", data->param[res].maxheld);
printf("\tfailcnt: %lu\n", data->param[res].failcnt);
}
}

static void print_stat_full(void *buf)
{
struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparmf_t param[UB_RESOURCES];
} *data;
int res;

data = buf;
for (res = 0; res < UB_RESOURCES; res++) {
printf("res %d\n", res);
printf("minheld: %lu\n", data->param[res].minheld);
printf("maxheld: %lu\n", data->param[res].maxheld);
printf("failcnt: %lu\n", data->param[res].failcnt);
}
}

static inline int res2func(int resource)
{
if (resource >= 0) {
print_stat = print_stat_one;
return UBSTAT_READ_ONE | resource;
}
if (resource == -1) {
print_stat = print_stat_all;
return UBSTAT_READ_ALL;
}
if (resource == -2) {
print_stat = print_stat_full;
return UBSTAT_READ_FULL;
}

printf("Bad resource %d\n", resource);
exit(1);
}

static void do_notify(int x)
{
int err;

err = sys_ubstat(func, luid, (unsigned long)&notif,
ubstat_buf, UBSTAT_BUFSIZE);
if (err < 0) {
perror("Can't set stat");
exit(0);
}

print_stat(ubstat_buf);
}

static int do_ubstat(int id, int period, int resource)
{
luid = id;
func = res2func(resource);
notif.maxinterval = period;
notif.signum = UBSTAT_NOTIFSIG;
signal(UBSTAT_NOTIFSIG, do_notify);
do_notify(0);
}

int main(int argc, char **argv)
{
int id, period, res;

if (argc == 1) {
usage();
return 0;
}

id = atoi(argv[1]);
period = atoi(argv[2]);
res = atoi(argv[3]);

do_ubstat(id, period, res);

while (1)
sleep(10);

return 0;
}
</source>

== Implementation constraints ==
Unfortunately the API is not architecture independent and thus 32-bit application will simply not work on x86_64.

[[Category:UBC]]

Ubstat system call

2011-01-20T14:06:31Z

Vdavydov:

This article describes an interesting system call which was designed to pick beancounters statistics

== Overview ==
The system call appeared in the very first version of the OpenVZ. Its API is rather sloppy, but this is something we have to live with due to backward compatibility reasons.

The main intention of this system call is to allow a user space process get the beancounters statistics ''periodically''. This statistics includes the fields observed in the <code>/proc/user_beancounters</code> file and one more field - the so called <code>minheld</code> value which is opposite to the <code>maxheld</code> one. As long as exporting the statistics the system call also notifies the task about the desired period has elapsed. The notification is performed by sending a signal to a process and this notification is one-shot.

== How it works ==
The typical usage of this call is in performing the following steps.
# Request the amount of resources
# Get the IDs of all the living beancounters
# Setup a handler for some signal (e.g. USR1)
# Perform a system call to setup the notification
# Go do something (or sleep for ever)

In a signal handler one should just perform a respective system call to get the stats and schedule the next notification (yes, they are performed in one go; see below for more details).

== API ==
The system call description is

<source lang="c">
long ubstat(int func, unsigned long luid, void *notif, void *buf, int size);
</source>

The macros and data typed used are declared in <code>include/ub/ub_stat.h</code> file.

=== Arguments description ===

'''<code>func</code>''' is like <code>cmd</code> in the <code>ioctl</code> system call. It can be one of
* <code>UBSTAT_READ_ONE</code> to read basic stats for one resource. The desired resource itself should be <code>or</code>-ed with the <code>func</code>
* <code>UBSTAT_READ_ALL</code> to read basic stats about all the resources
* <code>UBSTAT_READ_FULL</code> to read extended stats about all the resources
* <code>UBSTAT_UBLIST</code> to get the ids of the beancounters
* <code>UBSTAT_UBPARMNUM</code> to get the number of resources used by the kernel
* <code>UBSTAT_GETTIME</code>

See below for what ''basic'' and ''extended'' stats mean.

'''<code>luid</code>''' is the desired beancounter ID. Only one beancounter can be checked at one call.

'''<code>notif</code>''' is the pointer to a <code>ubnotifrq_t</code> structure which describes the notification details (see below).

'''<code>buf</code>''' is the pointer to a chunk of memory, which will contain the data requested.

'''<code>size</code>''' is the <code>buf</code> memory size.

=== The statistics format ===
The format of data returned into the buffer depends on the function requested.

'''1. <code>UBSTAT_READ_ONE</code>''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

typedef struct {
unsigned long maxheld;
unsigned long failcnt;
} ubstatparm_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[1];
}
</source>

It contains the time period for which the stats are returned and the <code>maxheld</code> and <code>failcnt</code> for the resource.

'''2. <code>UBSTAT_READ_ALL</code>''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

typedef struct {
unsigned long maxheld;
unsigned long failcnt;
} ubstatparm_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[UB_RESOURCES];
}
</source>

It contains the same info as the <code>UBSTAT_READ_ONE</code> does, but for all the resources.

'''3. <code>UBSTAT_READ_FULL</code>''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

typedef struct {
unsigned long barrier;
unsigned long limit;
unsigned long held;
unsigned long maxheld;
unsigned long minheld;
unsigned long failcnt;
unsigned long __unused1;
unsigned long __unused2;
} ubstatparmf_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparmf_t param[UB_RESOURCES];
}
</source>

It contains the extended info for all the resources.

'''4. UBSTAT_UBLIST''' treats the <code>buf</code> to point to the <code>unsigned long</code> array.

'''5. UBSTAT_UBPARMNUM''' ignores the <code>buf</code>.

'''6. UBSTAT_GETTIME''' format is
<source lang="c">
typedef unsigned long ubstattime_t;

struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstattime_t cur_time;
};
</source>

It returns the time interval within which the stats are collected and the current time.

All the times used are in seconds.

=== Notification ===
The notification info is passed via the <code>notif</code> argument and is being set up for all the functions except the <code>UBLIST</code> and the <code>UBPARNUM</code>. The notification is one-shot, but note that once you requested the statistics the next shot is scheduled at the same time.

The <code>notif</code> should point to
<source lang="c">
typedef struct {
long maxinterval;
int signum;
} ubnotifrq_t;
</source>

The <code>maxinterval</code> is the time after which the notification will be delivered. It should be more than 1 (second).

The <code>signum</code> is the signal that will be sent to notify.

=== Return value ===
The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code> it returns <code>UB_RESOURCES</code> and in all other cases it returns the amount of bytes written to the <code>buf</code>.

== Demo ==
The following program demonstrates how you can (but not should) use the described API. This example is deliberately made very stupid and simple to demonstrate the main idea and will only work on x86_64.
<source lang="c">
#include <stdio.h>
#include <unistd.h>
#include <stdlib.h>
#include <ub_stat.h>
#include <signal.h>

#define UBSTAT_BUFSIZE 4096
#define UBSTAT_NOTIFSIG SIGUSR1
#define UB_RESOURCES 24

static char ubstat_buf[UBSTAT_BUFSIZE];
static int luid, func;
static ubnotifrq_t notif;
static void (*print_stat)(void *buf);

#define sys_ubstat(args...) syscall(503, ## args)

static void usage(void)
{
printf("ubstat <id> <period> <resource>\n");
printf("resource can be either num or:\n");
printf("-1 for all maxheld and failcnt\n");
printf("-2 for all at all\n");
}

static void print_stat_one(void *buf)
{
struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[1];
} *data;

data = buf;

printf("maxheld: %lu\n", data->param[0].maxheld);
printf("failcnt: %lu\n", data->param[0].failcnt);
}

static void print_stat_all(void *buf)
{
struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparm_t param[UB_RESOURCES];
} *data;
int res;

data = buf;
for (res = 0; res < UB_RESOURCES; res++) {
printf("res %d\n", res);
printf("\tmaxheld: %lu\n", data->param[res].maxheld);
printf("\tfailcnt: %lu\n", data->param[res].failcnt);
}
}

static void print_stat_full(void *buf)
{
struct {
ubstattime_t start_time;
ubstattime_t end_time;
ubstatparmf_t param[UB_RESOURCES];
} *data;
int res;

data = buf;
for (res = 0; res < UB_RESOURCES; res++) {
printf("res %d\n", res);
printf("minheld: %lu\n", data->param[res].minheld);
printf("maxheld: %lu\n", data->param[res].maxheld);
printf("failcnt: %lu\n", data->param[res].failcnt);
}
}

static inline int res2func(int resource)
{
if (resource >= 0) {
print_stat = print_stat_one;
return UBSTAT_READ_ONE | resource;
}
if (resource == -1) {
print_stat = print_stat_all;
return UBSTAT_READ_ALL;
}
if (resource == -2) {
print_stat = print_stat_full;
return UBSTAT_READ_FULL;
}

printf("Bad resource %d\n", resource);
exit(1);
}

static void do_notify(int x)
{
int err;

err = sys_ubstat(func, luid, (unsigned long)&notif,
ubstat_buf, UBSTAT_BUFSIZE);
if (err < 0) {
perror("Can't set stat");
exit(0);
}

print_stat(ubstat_buf);
}

static int do_ubstat(int id, int period, int resource)
{
luid = id;
func = res2func(resource);
notif.maxinterval = period;
notif.signum = UBSTAT_NOTIFSIG;
signal(UBSTAT_NOTIFSIG, do_notify);
do_notify(0);
}

int main(int argc, char **argv)
{
int id, period, res;

if (argc == 1) {
usage();
return 0;
}

id = atoi(argv[1]);
period = atoi(argv[2]);
res = atoi(argv[3]);

do_ubstat(id, period, res);

while (1)
sleep(10);

return 0;
}
</source>

== Implementation constraints ==
Unfortunately the API is not architecture independent and thus 32-bit application will simply not work on x86_64.

[[Category:UBC]]