The Load module reports execution times and load information for threads
in a system
SYS/BIOS manages four distinct levels of execution threads: hardware
interrupt service routines, software interrupt routines, tasks, and
background idle functions. This module reports execution time and load on a
per-task basis, and also provides information globally for hardware
interrupt service routines, software interrupt routines and idle functions
(in the form of the idle task). It can also report an estimate of the
global CPU load, which is computed as the percentage of time in the
benchmark window which was NOT spent in the idle loop.
More specifically, the load is computed as follows:
global CPU load = 100 * (1 - (min. time for a trip around idle loop *
# times in idle loop)/(benchmark time window))
Any work done in the idle loop is included in the CPU load - in other
words, any time spent in the loop beyond the shortest trip around the idle
loop is counted as non-idle time.
The module relies on
update to be called to compute load and
execution times from the time when
update was last called. This
is automatically done for every period specified by
windowInMs in an
Idle
function when
updateInIdle is
set to true. The time between 2 calls to
update is called the
benchmark time window.
By passing in a function pointer of type
Void(*
postUpdate)(Void) through the
postUpdate config parameter, one can specify a
postUpdate function that is
automatically called by
update immediately after the statistics
have been computed at the end of a benchmark time window. Setting this
function allows the user to optionally post-process the thread statistics
once and only once per benchmark window.
Advanced users could optionally omit calling
update in the idle
loop by setting
updateInIdle to false. They can
then call
update somewhere else (e.g. in a periodic higher
priority Task) instead to ensure statistics are computed even when the
system is never idle.
Configuration example: The following statements configure the Load module
to obtain output in the CCS output window. This is useful for early
development without RTA tools support in SYS/BIOS:
var System = xdc.useModule('xdc.runtime.System');
var SysStd = xdc.useModule('xdc.runtime.SysStd');
System.SupportProxy = SysStd;
var Load = xdc.useModule('ti.sysbios.utils.Load');
var LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
var Defaults = xdc.useModule('xdc.runtime.Defaults');
var Diags = xdc.useModule('xdc.runtime.Diags');
// Turn on statistics log messages for Load module
Load.common$.diags_USER4 = Diags.ALWAYS_ON;
// Define a program-wide logger to be the System Logger
Defaults.common$.logger = LoggerSys.create();
typedef Load_FuncPtr |
|
Callback function type
typedef Void (*Load_FuncPtr)();
struct Load_Stat |
|
Load statistics info
typedef struct Load_Stat {
UInt32 threadTime;
UInt32 totalTime;
} Load_Stat;
config Load_LS_cpuLoad // module-wide |
|
This event logs the global CPU load as a percentage
DETAILS
This event is logged whenever the Diags.USER4 level is enabled
and the load is measured.
config Load_LS_hwiLoad // module-wide |
|
This event logs the Hwi load
DETAILS
This event is logged whenever the Diags.USER4 level is enabled
hwiEnabled is true, and the load is measured.
This event logs the Hwi load, with the form:
<load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
config Load_LS_swiLoad // module-wide |
|
This event logs the Swi load
DETAILS
This event is logged whenever the Diags.USER4 level is enabled
swiEnabled is true, and the load is measured.
This event logs the Swi load, with the form:
<load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
config Load_LS_taskLoad // module-wide |
|
This event logs Task thread loads
DETAILS
This event is logged whenever the Diags.USER4 level is enabled,
taskEnabled is true, and the load is measured.
This event logs Task thread loads, with the form:
<Task handle>,<load time>,<measurement time>,<Task function pointer>
Percentage load = <load time> / <measurement time> x 100%
config Load_hwiEnabled // module-wide |
|
Enables Hwi time monitoring
extern const Bool Load_hwiEnabled;
DETAILS
When this parameter is set to
true,
Hwi
processing time is accumulated between successive calls of
update and, as part of Load_update, an
event with this cumulative time is logged. This
time, together with the total elapsed time, is used to estimate the
CPU load due to any Hwi instances run between these updates.
config Load_postUpdate // module-wide |
|
User function called after each load update
DETAILS
If non-NULL, postUpdate is run immediately after each update.
config Load_swiEnabled // module-wide |
|
Enables Swi time monitoring
extern const Bool Load_swiEnabled;
DETAILS
When this parameter is set to
true, Swi processing time is
accumulated between successive calls of
update and, as
part of Load_update, an
event with this
cumulative time is logged. This time together with the total
elapsed time is used to estimate the CPU load due to any Swi
instances run between these updates.
config Load_taskEnabled // module-wide |
|
Enables Task time monitoring
extern const Bool Load_taskEnabled;
DETAILS
When this parameter is set to
true, each Task's processing time is
accumulated between successive calls of
update and, as
part of Load_update, an
event with this
cumulative time is logged for each task. This time together with the
total elapsed time is used to estimate the CPU load due to each Task
run between these updates.
config Load_updateInIdle // module-wide |
|
Automatically call update in Idle loop
extern const Bool Load_updateInIdle;
DETAILS
If this parameter is set to
true, an
Idle
function, which computes and updates the CPU load, is added to the
Idle loop.
config Load_windowInMs // module-wide |
|
Load averaging period
extern const UInt Load_windowInMs;
DETAILS
When
updateInIdle is enabled, this period determines the
minimum elapsed time between updates of the load statistics in the
idle loop.
Load_calculateLoad() // module-wide |
|
Compute total CPU load from a Load_Stat structure
DETAILS
This function computes percent load from the
values in a Load_Stat structure.
RETURNS
Load value of a Load_Stat structure in %.
Load_getCPULoad() // module-wide |
|
Return an estimate of the global CPU load
UInt32 Load_getCPULoad();
RETURNS
CPU load in %
DETAILS
This function returns an estimate of CPU load (% utilization of the
CPU), with the idle time determined based on number of trips through
the idle loop multiplied by the shortest amount of time through the
loop.
This function requires the idle loop to be run during a benchmark time
window.
Note: Time spent in kernel while switching to a Hwi/Swi/Task is
considered non-idle time.
Load_getGlobalHwiLoad() // module-wide |
|
Return the load and time spent in hwi's
ARGUMENTS
stat
Load and time statistics info
RETURNS
TRUE if success, FALSE if failure
DETAILS
This function computes the load and time spent in Hwi's along
with the time duration over which the measurement was done. Numbers
are reported in
Timestamp counts.
Load_getGlobalSwiLoad() // module-wide |
|
Return the load and time spent in Swi's
ARGUMENTS
stat
Load and time statistics info
RETURNS
TRUE if success, FALSE if failure
DETAILS
This function returns the load and time spent in Swi's along with
the time duration over which the measurement was done. Numbers are
reported in
Timestamp counts.
Load_getTaskLoad() // module-wide |
|
Return the load and time spent in a specific task
ARGUMENTS
task
Handle of the Task which time we are interested in.
stat
Load and time statistics info
RETURNS
TRUE if success, FALSE if failure
DETAILS
This function returns the load and time spent in a specific task
along with the duration over which the measurement was done. Numbers
are reported in
Timestamp counts.
Task handle must be valid and have been registered with Load.
Load_reset() // module-wide |
|
Reset all internal load counters
DETAILS
If
taskEnabled is set to true, this function can
only be called in task context.
Load_setMinIdle() // module-wide |
|
Set lower bound on idle loop time used to compute CPU load
UInt32 Load_setMinIdle(UInt32 newMinIdleTime);
SEE
Load_update() // module-wide |
|
Record thread statistics and reset all counters
DETAILS
If
taskEnabled is set to true, this function can
only be called in task context.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Load_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Load_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Load_Module_getMask();
// Returns the diagnostics mask for this module
Void Load_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
struct Load.Stat |
|
Load statistics info
XDCscript usage |
meta-domain |
var obj = new Load.Stat;
obj.threadTime = UInt32 ...
obj.totalTime = UInt32 ...
C SYNOPSIS
config Load.LS_cpuLoad // module-wide |
|
This event logs the global CPU load as a percentage
XDCscript usage |
meta-domain |
msg: "LS_cpuLoad: %d%%"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled
and the load is measured.
C SYNOPSIS
config Load.LS_hwiLoad // module-wide |
|
This event logs the Hwi load
XDCscript usage |
meta-domain |
msg: "LS_hwiLoad: %d,%d"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled
hwiEnabled is true, and the load is measured.
This event logs the Hwi load, with the form:
<load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
C SYNOPSIS
config Load.LS_swiLoad // module-wide |
|
This event logs the Swi load
XDCscript usage |
meta-domain |
msg: "LS_swiLoad: %d,%d"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled
swiEnabled is true, and the load is measured.
This event logs the Swi load, with the form:
<load time>,<measurement time>
Percentage load = <load time> / <measurement time> x 100%
C SYNOPSIS
config Load.LS_taskLoad // module-wide |
|
This event logs Task thread loads
XDCscript usage |
meta-domain |
msg: "LS_taskLoad: 0x%x,%d,%d,0x%x"
};
DETAILS
This event is logged whenever the Diags.USER4 level is enabled,
taskEnabled is true, and the load is measured.
This event logs Task thread loads, with the form:
<Task handle>,<load time>,<measurement time>,<Task function pointer>
Percentage load = <load time> / <measurement time> x 100%
C SYNOPSIS
config Load.hwiEnabled // module-wide |
|
Enables Hwi time monitoring
XDCscript usage |
meta-domain |
Load.hwiEnabled = Bool false;
DETAILS
When this parameter is set to
true,
Hwi
processing time is accumulated between successive calls of
update and, as part of Load_update, an
event with this cumulative time is logged. This
time, together with the total elapsed time, is used to estimate the
CPU load due to any Hwi instances run between these updates.
C SYNOPSIS
config Load.postUpdate // module-wide |
|
User function called after each load update
XDCscript usage |
meta-domain |
Load.postUpdate = Void(*)() null;
DETAILS
If non-NULL, postUpdate is run immediately after each update.
C SYNOPSIS
config Load.swiEnabled // module-wide |
|
Enables Swi time monitoring
XDCscript usage |
meta-domain |
Load.swiEnabled = Bool false;
DETAILS
When this parameter is set to
true, Swi processing time is
accumulated between successive calls of
update and, as
part of Load_update, an
event with this
cumulative time is logged. This time together with the total
elapsed time is used to estimate the CPU load due to any Swi
instances run between these updates.
C SYNOPSIS
config Load.taskEnabled // module-wide |
|
Enables Task time monitoring
XDCscript usage |
meta-domain |
Load.taskEnabled = Bool true;
DETAILS
When this parameter is set to
true, each Task's processing time is
accumulated between successive calls of
update and, as
part of Load_update, an
event with this
cumulative time is logged for each task. This time together with the
total elapsed time is used to estimate the CPU load due to each Task
run between these updates.
C SYNOPSIS
config Load.updateInIdle // module-wide |
|
Automatically call update in Idle loop
XDCscript usage |
meta-domain |
Load.updateInIdle = Bool true;
DETAILS
If this parameter is set to
true, an
Idle
function, which computes and updates the CPU load, is added to the
Idle loop.
C SYNOPSIS
config Load.windowInMs // module-wide |
|
Load averaging period
XDCscript usage |
meta-domain |
Load.windowInMs = UInt 500;
DETAILS
When
updateInIdle is enabled, this period determines the
minimum elapsed time between updates of the load statistics in the
idle loop.
C SYNOPSIS
metaonly config Load.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
metaonly config Load.minIdle // module-wide |
|
Specifies the minimum time used to compute idle time
XDCscript usage |
meta-domain |
DETAILS
During CPU load measurement, the minimum time observed executing
the idle loop together with the count of the number of times the idle
loop runs id used to compute the total idle time. However, since the
_actual_ time spent in the idle loop will almost always be greater
then the observed minimum, the idle time is almost always under
estimated.
This configuration parameter can be used to compensate for this
underestimate by placing a lower bound on the minimum time used in
the CPU measurements. The minimum idle time used to compute CPU
load is guarenteed to be greater than or equal to minIdle.