NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO
#include <mkstat/mkstat.h>mkStatMem(KnMemStat * mem, KnMemStatCtl * ctl);
The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.
See API(5FEA) for details.
The
MKSTAT
module features the following system calls:
Microkernel memory statistics. The C_OS uses
mkStatMem()
to implement the
kern.mkstats.mem
sysctl()
node, when the
OS_GAUGES
feature is set to
true.
Microkernel allocated supervisor page statistics. The C_OS uses
mkStatSvPages()
to implement the
kern.mkstats.svpages
sysctl()
node, when the
OS_GAUGES
feature is set to
true.
Microkernel execution statistics. The C_OS uses
mkStatActors()
to implement the
kern.mkstats.actors
sysctl()
node, when the
OS_GAUGES
feature is set to
true
.
Microkernel execution statistics. The C_OS uses
mkStatThreads()
to implement the
kern.mkstats.threads
sysctl()
node, when the
OS_GAUGES
feature is set to
true
Microkernel CPU statistics. The C_OS uses mkStatCpu() to implement the kern.mkstats.cpu sysctl() node. The VTIMER module must be set to ON .
/* * CPU usage statistics */ typedef struct { KnTimeVal external; KnTimeVal internal; KnTimeVal totalCpu; } KnCpuStat;/
Microkernel per-actor statistics. The C_OS uses mkStatActorMem() to implement the /proc interface, to handle the per_process_virtual_pages gauge.
When
OS_GAUGES
is set to
true
:
If a process, this system call can only be used in read mode; the /proc interface must be used for control mode (the system events generated for alarms will have a PID)
If not a process, the system call can be used in control mode (in this case, the C_OS will transform the
MKSTAT
events generated for such alarms in system events with a
KnCap
)
WARNING: the
MKSTAT
module does not check whether an actor is a process or not: the caller in control mode has to be sure it is not a process.
/* * actor memory statistics */ typedef struct { KnGauge32Threshold virtPages; KnGauge32 physPages; KnGauge32 lockPages; } KnActMemStat;
Note that physPages and lockPages are simple gauges (read only, no watermarks).
Using the kern actor capability is not recommended, because results may be unpredictable; for example, all supervisor regions, even belonging to other actors than the microkernel, will be seen as attached to the kern actor. It is recommended not to set a threshold on virtPages for that particular actor, or not to use it at all.
Microkernel per-supervisor actor statistics. In addition to mkStatActorMem() , mkStatActorSvPages() is another threshold per actor for supervisor actors. This call is used by the OS layer; the C_OS does not use mkStatActorSvPages() .
This system call can be used in control mode. In this case, the C_OS transforms the
MKSTAT
events generated for such
alarms in system events with a
KnCap
.
/* * Per actor svpages memory statistics */ typedef struct { KnGauge32Threshold svPages; } KnActSvPagesStat; /* * Per actor svpages memory statistics control */ typedef KnGauge32ThresholdCtl KnActSvPagesStatCtl;
Microkernel per-thread statistics. This API is only used by the OS layer. The C_OS uses it to implement the /proc interface, to handle the per-thread stats.
/* * Thread cpu statistics */ typedef struct { KnTimeVal external; KnTimeVal internal; KnCounter32 waitingCnt; } KnThreadCpuStat;
Microkernel
MKSTAT
event control. This API is only used by the OS
layer. The C_OS uses it to start or stop
MKSTAT
event generation.
nbEvts is the maximum possible number of buffered events, set by the kern.mkstat.maxevents tunable. nbEvts is a read-only value.
ctrl can take one of the following values:
Starts
MKSTAT
event generation
Stops
MKSTAT
event generation
Actor creation/deletion signaling is active
Actor creation/deletion are not signaled
Never use this system call when
OS_GAUGES
is true.
Microkernel
MKSTAT
events waiting.
mkStatEvtWait()
is
only used by the OS layer. The C_OS uses it in a high thread to read
MKSTAT
events and transform them into system
events.
This system call must never be used when
OS_GAUGES
is true.
From %lt;mkstat/knSysGauges.h> /* * MKSTAT event */ typedef struct { void *ident; void *cookie; int type; KnCap cap; KnGauge32Wmark gauge; } KnMkstatEvt;
The type field is used to determine the type of alarms (RISE or CLEAR) and the signaling of actors (CREATE/DESTROY). In addition, it holds a signature, to relay an alarm to a threshold, for example for physcal memory or for actors.
From %lt;mkstat/knGauges.h> // Threshold Events type #define THRESHOLD_EVENT_RISE 0x01 #define THRESHOLD_EVENT_CLEAR 0x02 From %lt;mkstat/knSysGauges.h> #define MKSTAT_EVT_TYPE_ALARM_RISE THRESHOLD_EVENT_RISE #define MKSTAT_EVT_TYPE_ALARM_CLEAR THRESHOLD_EVENT_CLEAR #define MKSTAT_EVT_TYPE_ACTOR_CREATE 0x4 #define MKSTAT_EVT_TYPE_ACTOR_DESTROY 0x8 #define MKSTAT_EVT_TYPE_MASK 0x0000ffff #define MKSTAT_EVT_MASK 0xffff0000 #define MKSTAT_EVT_ACTORS (0x00010000) #define MKSTAT_EVT_THREADS (0x00020000) #define MKSTAT_EVT_SVPAGES (0x00040000) #define MKSTAT_EVT_PHYSMEM (0x00080000) #define MKSTAT_EVT_PER_ACTOR_MEM (0x00100000) #define MKSTAT_EVT_PER_ACTOR_SVPAGES (0x00200000)
The
ident
field is for private use (used when
OS_GAUGES
is true).
cap is only valued when type is THRESHOLD_EVENT_ACTOR_CREATE/DESTROY , otherwhise, it returns a NULL KnCap .
gauge is only valued when type is an alarm.
Note that
MKSTAT
event generation never fails internally. If an
MKSTAT
event consumer is
not present, or is too slow, the oldest buffered events will be silently discarded and replaced by new ones.
hitCounter
is reserved
for counting system event generation failures; it is not handled by the
MKSTAT
module, but by the C_OS. The internal
MKSTAT
event recording function can be called from anywhere: it never blocks or changes the caller's excution flow.
The
MKSTAT
system calls return
K_OK
upon success, or one of the error codes below upon failure.
The event has been aborted
A threshold cannot be activated without having been valued at least once
Both _CTL_THRESHOLD_ACTIVATE and _CTL_THRESHOLD_DISACTIVATE have been requested. Only one choice is possible
One of the parameters is invalid
The OS does not have the features for gauges or thresholds available. Use configurator to activate this feature ( MKSTAT=true )
A user actor made the call;
MKSTAT
system calls are reserved for supervisor actors
For a high threshold, the clear value must be less than the rise value. For a low threshold, the rise value must be less than the clear value
A threshold cannot be set if active
A timeout occured
Clear and/or rise values are not in the permitted range for that gauge; for example, for actor gauges the range is from 0 to maxActors
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
NAME | SYNOPSIS | API RESTRICTIONS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO