Editing Ubstat system call
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.
The edit can be undone.
Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision | Your text | ||
Line 6: | Line 6: | ||
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. | 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. | The typical usage of this call is in performing the following steps. | ||
# Request the amount of resources | # Request the amount of resources | ||
Line 16: | Line 16: | ||
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). | 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 == | + | === API === |
The system call description is | The system call description is | ||
− | < | + | <pre> |
long ubstat(int func, unsigned long luid, void *notif, void *buf, int size); | long ubstat(int func, unsigned long luid, void *notif, void *buf, int size); | ||
− | </ | + | </pre> |
The macros and data typed used are declared in <code>include/ub/ub_stat.h</code> file. | 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>func</code>''' is like <code>cmd</code> in the <code>ioctl</code> system call. It can be one of | ||
Line 45: | Line 45: | ||
'''<code>size</code>''' is the <code>buf</code> memory size. | '''<code>size</code>''' is the <code>buf</code> memory size. | ||
− | + | == The statistics format == | |
− | The format of data | + | The format of data rerurned into the buffer depends on the function requested. |
'''1. <code>UBSTAT_READ_ONE</code>''' format is | '''1. <code>UBSTAT_READ_ONE</code>''' format is | ||
− | < | + | <pre> |
typedef unsigned long ubstattime_t; | typedef unsigned long ubstattime_t; | ||
Line 62: | Line 62: | ||
ubstatparm_t param[1]; | ubstatparm_t param[1]; | ||
} | } | ||
− | </ | + | </pre> |
It contains the time period for which the stats are returned and the <code>maxheld</code> and <code>failcnt</code> for the resource. | 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 | '''2. <code>UBSTAT_READ_ALL</code>''' format is | ||
− | < | + | <pre> |
typedef unsigned long ubstattime_t; | typedef unsigned long ubstattime_t; | ||
Line 80: | Line 80: | ||
ubstatparm_t param[UB_RESOURCES]; | ubstatparm_t param[UB_RESOURCES]; | ||
} | } | ||
− | </ | + | </pre> |
It contains the same info as the <code>UBSTAT_READ_ONE</code> does, but for all the resources. | 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 | '''3. <code>UBSTAT_READ_FULL</code>''' format is | ||
− | < | + | <pre> |
typedef unsigned long ubstattime_t; | typedef unsigned long ubstattime_t; | ||
Line 104: | Line 104: | ||
ubstatparmf_t param[UB_RESOURCES]; | ubstatparmf_t param[UB_RESOURCES]; | ||
} | } | ||
− | </ | + | </pre> |
It contains the extended info for all the resources. | It contains the extended info for all the resources. | ||
Line 113: | Line 113: | ||
'''6. UBSTAT_GETTIME''' format is | '''6. UBSTAT_GETTIME''' format is | ||
− | < | + | <pre> |
typedef unsigned long ubstattime_t; | typedef unsigned long ubstattime_t; | ||
Line 121: | Line 121: | ||
ubstattime_t cur_time; | ubstattime_t cur_time; | ||
}; | }; | ||
− | </ | + | </pre> |
It returns the time interval within which the stats are collected and the current time. | It returns the time interval within which the stats are collected and the current time. | ||
Line 131: | Line 131: | ||
The <code>notif</code> should point to | The <code>notif</code> should point to | ||
− | < | + | <pre> |
typedef struct { | typedef struct { | ||
long maxinterval; | long maxinterval; | ||
int signum; | int signum; | ||
} ubnotifrq_t; | } ubnotifrq_t; | ||
− | </ | + | </pre> |
The <code>maxinterval</code> is the time after which the notification will be delivered. It should be more than 1 (second). | The <code>maxinterval</code> is the time after which the notification will be delivered. It should be more than 1 (second). | ||
Line 143: | Line 143: | ||
=== Return value === | === Return value === | ||
− | The system call returns -1 in case error has occurred. In case of <code>UBSTAT_UBPARMNUM</code | + | 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 == | == 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. | 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. | ||
− | < | + | <pre> |
#include <stdio.h> | #include <stdio.h> | ||
#include <unistd.h> | #include <unistd.h> | ||
Line 285: | Line 285: | ||
return 0; | return 0; | ||
} | } | ||
− | </ | + | </pre> |
== Implementation constraints == | == Implementation constraints == |