Load.h File Reference

Detailed Description

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.

Execution time is reported in units of Timestamp counts, and load is reported in percentages.

By default, load data is gathered for Task threads. Load_hwiEnabled, Load_swiEnabled and Load_taskEnabled can be used to select which type(s) of threads are monitored. Users can also choose to call Load_getTaskLoad, Load_getGlobalSwiLoad, Load_getGlobalHwiLoad and Load_getCPULoad at any time to obtain the statistics at runtime.

The module relies on Load_update to be called to compute load and execution times from the time when Load_update was last called. This is automatically done for every period specified by Load_windowInMs in an Idle function when Load_updateInIdle is set to true. The time between two calls to Load_update is called the benchmark time window.

By passing in a function pointer of type void(*Load_postUpdate)(void) through the Load_postUpdate config parameter, one can specify a Load_postUpdate function that is automatically called by Load_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 Load_update in the idle loop by setting Load_updateInIdle to false. They can then call Load_update somewhere else (e.g. in a periodic higher priority Task) instead to ensure statistics are computed even when the system is never idle.

CPU Load Calculation Methods

The CPU load is computed in three different ways, depending on what threads are monitored, and whether or not Power management is used to idle the CPU when no threads are running.

Task Load Disabled and No Power Management

The first method of calculating CPU load is used when Task load monitoring is disabled, ie, Load_taskEnabled is false, and Power management is not used. The CPU load 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.

This method works fairly well if the timestamp frequency is sufficiently high (for example, if it's equal to the CPU frequency). The CPU load accuracy can also be affected by caching and user idle functions.

Task Load Enabled and No Power Management

The second method of calculating CPU load is used when Task load monitoring is enabled (Load_taskEnabled = true) and Power management is not used. In this case the CPU load is calculted as

global CPU load = 100 - (Idle task load)

This prevents any discrepancy between the calculated CPU load had we used the first method, and 100 - the Idle task load. If Swi and Hwi load monitoring are not enabled, however, time spent in a Swi or Hwi will be charged to the task in which it ran. This will affect the accuracy of the CPU (and Task) load, but the trade off is more overhead to do the Hwi and Swi load monitoring.

Power Management Enabled

The Load module is dependent on the timestamp timer, thus the latter must continue to run during idle, in order to accurately measure idle and non-idle time. On platforms where the timestamp timer is halted during sleep (e.g. CC32XX), the Load module can only report correct numbers when power management is disabled. On other platforms where the timer continues to run during sleep, the best way to get CPU load is to make sure that Load_taskEnabled is set to true. Then the CPU load will be calculated as 100 - the idle task load. However, for BIOS in ROM builds, this method will not work, as Task hooks are not allowed. So to use Load for any devices that support BIOS in ROM builds, make sure the ROM build is disabled.

Caveats

• For the module to return accurate load values, the Load_update function must be run at least once before the Timestamp count gets to wrap around. This means on a platform with a 32-bit Timestamp frequency that runs at 200 MHz, the function must be called at least once every 21 sec. With faster Timestamp frequencies it would have to be called even more frequently.
• If the Load_updateInIdle option is enabled, the module will call Load_update periodically according to Load_windowInMs. The latter must be set to a time interval that is below (2^32) * 1000 / (Timestamp Frequency) milliseconds
• If the Load_updateInIdle option is disabled, the user is then responsible for calling Load_update more often than the above time interval.
• Load values might not add up to 100%. Because the module minimizes its interrupt latency and avoids locking up the system to compute all thread loads at once, each thread's execution time is evaluated separately over its own time window, which could be slightly different to that of another thread.
• When disabling monitoring of a thread type of higher priority, the time spent in that thread type will be counted towards time spent in threads of lower priority. E.g. if Load_hwiEnabled and Load_swiEnabled are both false, then time spent in Hwi's and Swi's will be counted towards the Tasks in which the interrupts happened. Thus, for better accuracy, it is best to leave monitoring on for threads of a higher priority relative to the thread type of interest.
• When Task load monitoring is not enabled and Power management is not used, the implementation of Load_getCPULoad() self-calibrates the shortest path through the idle loop. It does this by keeping track of the shortest time between invocations of an idle function automatically inserted by the Load module, and assumes that to be the time it takes for one iteration through the idle loop. Because of this, the CPU load value is only an estimate since the idle loop might occasionally take longer to run (e.g. due to caching effects, stalls). The reported CPU load tends to be slightly higher than reality, especially when the load is low.
• Currently does not support Timestamp frequencies over 4 GHz.

Calling Context

Function	Hwi	Swi	Task	Main	Startup
getCPULoad	Y	Y	Y	N	N
getGlobalHwiLoad	Y	Y	Y	N	N
getGlobalSwiLoad	Y	Y	Y	N	N
getTaskLoad	Y	Y	Y	N	N
reset	Y*	Y*	Y	Y	N
update	Y*	Y*	Y	N	N
Definitions: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. Load_Module_startupDone() returns true). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. Load_Module_startupDone() returns false). *: Indicates only when taskEnabled is set to false.

#include <xdc/std.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/knl/Queue.h>
#include <ti/sysbios/knl/Task.h>
#include <ti/sysbios/hal/Hwi.h>
#include <ti/sysbios/runtime/Error.h>
#include "Load_defs.h"

Include dependency graph for Load.h:

Go to the source code of this file.

Data Structures
struct	Load_Stat
	Load statistics info. More...
struct	Load_Module_State

Macros
#define	ti_sysbios_utils_Load_long_names
#define	Load_module   ((Load_Module_State *) &(Load_Module_state))

Typedefs
typedef void(*	Load_FuncPtr) (void)
	Callback function type. More...

Functions
void	Load_init (void)
bool	Load_getTaskLoad (Task_Handle task, Load_Stat *stat)
	Return the load and time spent in a specific task. More...
void	Load_update ()
	Record thread statistics and reset all counters. More...
void	Load_reset ()
	Reset all internal load counters. More...
bool	Load_getGlobalSwiLoad (Load_Stat *stat)
	Return the load and time spent in Swi's. More...
bool	Load_getGlobalHwiLoad (Load_Stat *stat)
	Return the load and time spent in hwi's. More...
uint32_t	Load_getCPULoad ()
	Return an estimate of the global CPU load. More...
uint32_t	Load_calculateLoad (Load_Stat *stat)
	Compute total CPU load from a Load_Stat structure. More...
uint32_t	Load_setMinIdle (uint32_t newMinIdleTime)
	Set lower bound on idle loop time used to compute CPU load. More...
void	Load_addTask (Task_Handle task, Load_HookContext *env)
	Add a task to the list for benchmarking. More...
bool	Load_removeTask (Task_Handle taskHandle)
	Remove a task from the list for benchmarking. More...

Macro Definition Documentation

ti_sysbios_utils_Load_long_names

#define ti_sysbios_utils_Load_long_names

Load_module

#define Load_module   ((Load_Module_State *) &(Load_Module_state))

Typedef Documentation

Load_FuncPtr

typedef void(* Load_FuncPtr) (void)

Callback function type.

Function Documentation

Load_init()

void Load_init

(

void

)

Load_getTaskLoad()

bool Load_getTaskLoad	(	Task_Handle	task,
		Load_Stat *	stat
	)

Return the load and time spent in a specific task.

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.

Parameters

task	Handle of the Task which time we are interested in.
stat	Load and time statistics info

Return values

true	if success, false if failure

Load_update()

void Load_update

(

)

Record thread statistics and reset all counters.

If Load_taskEnabled is set to true, this function can only be called in task context.

Load_reset()

void Load_reset

(

)

Reset all internal load counters.

If Load_taskEnabled is set to true, this function can only be called in task context.

Load_getGlobalSwiLoad()

bool Load_getGlobalSwiLoad

(

Load_Stat *

stat

)

Return the load and time spent in Swi's.

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.

Parameters

stat	Load and time statistics info

Return values

true	if success, false if failure

Load_getGlobalHwiLoad()

bool Load_getGlobalHwiLoad

(

Load_Stat *

stat

)

Return the load and time spent in hwi's.

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.

Parameters

stat	Load and time statistics info

Return values

true	if success, false if failure

Load_getCPULoad()

uint32_t Load_getCPULoad

(

)

Return an estimate of the global CPU load.

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.

Return values

CPU

load in %

Load_calculateLoad()

uint32_t Load_calculateLoad

(

Load_Stat *

stat

)

Compute total CPU load from a Load_Stat structure.

This function computes percent load from the values in a Load_Stat structure.

Return values

Load	value of a Load_Stat structure in %.

Load_setMinIdle()

uint32_t Load_setMinIdle

(

uint32_t

newMinIdleTime

)

Set lower bound on idle loop time used to compute CPU load.

See also

Load_minIdle

Load_addTask()

void Load_addTask	(	Task_Handle	task,
		Load_HookContext *	env
	)

Add a task to the list for benchmarking.

If Load_taskEnabled is set to true, this function can only be called in task context.

Parameters

task	Handle of the Task to be added to the list.
env	Handle of context structure to be used by the Task

Load_removeTask()

bool Load_removeTask

(

Task_Handle

taskHandle

)

Remove a task from the list for benchmarking.

If Load_taskEnabled is set to true, this funciton can only be called in task context.

Parameters

taskHandle

Handle of the Task to be removed from the list.