1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
5 | .. COMMENT: All rights reserved. |
---|
6 | |
---|
7 | .. index:: CPU Usage |
---|
8 | |
---|
9 | CPU Usage Statistics |
---|
10 | ******************** |
---|
11 | |
---|
12 | Introduction |
---|
13 | ============ |
---|
14 | |
---|
15 | The CPU usage statistics manager is an RTEMS support component that provides a |
---|
16 | convenient way to manipulate the CPU usage information associated with each |
---|
17 | task The routines provided by the CPU usage statistics manager are: |
---|
18 | |
---|
19 | - rtems_cpu_usage_report_ - Report CPU Usage Statistics |
---|
20 | |
---|
21 | - rtems_cpu_usage_reset_ - Reset CPU Usage Statistics |
---|
22 | |
---|
23 | Background |
---|
24 | ========== |
---|
25 | |
---|
26 | When analyzing and debugging real-time applications, it is important to be able |
---|
27 | to know how much CPU time each task in the system consumes. This support |
---|
28 | component provides a mechanism to easily obtain this information with little |
---|
29 | burden placed on the target. |
---|
30 | |
---|
31 | The raw data is gathered as part of performing a context switch. RTEMS keeps |
---|
32 | track of how many clock ticks have occurred which the task being switched out |
---|
33 | has been executing. If the task has been running less than 1 clock tick, then |
---|
34 | for the purposes of the statistics, it is assumed to have executed 1 clock |
---|
35 | tick. This results in some inaccuracy but the alternative is for the task to |
---|
36 | have appeared to execute 0 clock ticks. |
---|
37 | |
---|
38 | RTEMS versions newer than the 4.7 release series, support the ability to obtain |
---|
39 | timestamps with nanosecond granularity if the BSP provides support. It is a |
---|
40 | desirable enhancement to change the way the usage data is gathered to take |
---|
41 | advantage of this recently added capability. Please consider sponsoring the |
---|
42 | core RTEMS development team to add this capability. |
---|
43 | |
---|
44 | Operations |
---|
45 | ========== |
---|
46 | |
---|
47 | Report CPU Usage Statistics |
---|
48 | --------------------------- |
---|
49 | |
---|
50 | The application may dynamically report the CPU usage for every task in the |
---|
51 | system by calling the ``rtems_cpu_usage_report`` routine. This routine prints |
---|
52 | a table with the following information per task: |
---|
53 | |
---|
54 | - task id |
---|
55 | |
---|
56 | - task name |
---|
57 | |
---|
58 | - number of clock ticks executed |
---|
59 | |
---|
60 | - percentage of time consumed by this task |
---|
61 | |
---|
62 | The following is an example of the report generated: |
---|
63 | |
---|
64 | .. code-block:: c |
---|
65 | |
---|
66 | +------------------------------------------------------------------------------+ |
---|
67 | |CPU USAGE BY THREAD | |
---|
68 | +-----------+----------------------------------------+-------------------------+ |
---|
69 | |ID | NAME | SECONDS | PERCENT | |
---|
70 | +-----------+----------------------------------------+---------------+---------+ |
---|
71 | |0x04010001 | IDLE | 0 | 0.000 | |
---|
72 | +-----------+----------------------------------------+---------------+---------+ |
---|
73 | |0x08010002 | TA1 | 1203 | 0.748 | |
---|
74 | +-----------+----------------------------------------+---------------+---------+ |
---|
75 | |0x08010003 | TA2 | 203 | 0.126 | |
---|
76 | +-----------+----------------------------------------+---------------+---------+ |
---|
77 | |0x08010004 | TA3 | 202 | 0.126 | |
---|
78 | +-----------+----------------------------------------+---------------+---------+ |
---|
79 | |TICKS SINCE LAST SYSTEM RESET: 1600 | |
---|
80 | |TOTAL UNITS: 1608 | |
---|
81 | +------------------------------------------------------------------------------+ |
---|
82 | |
---|
83 | Notice that the ``TOTAL UNITS`` is greater than the ticks per reset. This is |
---|
84 | an artifact of the way in which RTEMS keeps track of CPU usage. When a task is |
---|
85 | context switched into the CPU, the number of clock ticks it has executed is |
---|
86 | incremented. While the task is executing, this number is incremented on each |
---|
87 | clock tick. Otherwise, if a task begins and completes execution between |
---|
88 | successive clock ticks, there would be no way to tell that it executed at all. |
---|
89 | |
---|
90 | Another thing to keep in mind when looking at idle time, is that many systems - |
---|
91 | especially during debug - have a task providing some type of debug interface. |
---|
92 | It is usually fine to think of the total idle time as being the sum of the |
---|
93 | ``IDLE`` task and a debug task that will not be included in a production build |
---|
94 | of an application. |
---|
95 | |
---|
96 | Reset CPU Usage Statistics |
---|
97 | -------------------------- |
---|
98 | |
---|
99 | Invoking the ``rtems_cpu_usage_reset`` routine resets the CPU usage statistics |
---|
100 | for all tasks in the system. |
---|
101 | |
---|
102 | Directives |
---|
103 | ========== |
---|
104 | |
---|
105 | This section details the CPU usage statistics manager's directives. A |
---|
106 | subsection is dedicated to each of this manager's directives and describes the |
---|
107 | calling sequence, related constants, usage, and status codes. |
---|
108 | |
---|
109 | .. raw:: latex |
---|
110 | |
---|
111 | \clearpage |
---|
112 | |
---|
113 | .. index:: rtems_cpu_usage_report |
---|
114 | |
---|
115 | .. _rtems_cpu_usage_report: |
---|
116 | |
---|
117 | cpu_usage_report - Report CPU Usage Statistics |
---|
118 | ---------------------------------------------- |
---|
119 | |
---|
120 | CALLING SEQUENCE: |
---|
121 | .. code-block:: c |
---|
122 | |
---|
123 | void rtems_cpu_usage_report( void ); |
---|
124 | |
---|
125 | STATUS CODES: |
---|
126 | NONE |
---|
127 | |
---|
128 | DESCRIPTION: |
---|
129 | This routine prints out a table detailing the CPU usage statistics for all |
---|
130 | tasks in the system. |
---|
131 | |
---|
132 | NOTES: |
---|
133 | The table is printed using the ``printk`` routine. |
---|
134 | |
---|
135 | .. raw:: latex |
---|
136 | |
---|
137 | \clearpage |
---|
138 | |
---|
139 | .. index:: rtems_cpu_usage_reset |
---|
140 | |
---|
141 | .. _rtems_cpu_usage_reset: |
---|
142 | |
---|
143 | cpu_usage_reset - Reset CPU Usage Statistics |
---|
144 | -------------------------------------------- |
---|
145 | |
---|
146 | CALLING SEQUENCE: |
---|
147 | .. code-block:: c |
---|
148 | |
---|
149 | void rtems_cpu_usage_reset( void ); |
---|
150 | |
---|
151 | STATUS CODES: |
---|
152 | NONE |
---|
153 | |
---|
154 | DESCRIPTION: |
---|
155 | This routine re-initializes the CPU usage statistics for all tasks in the |
---|
156 | system to their initial state. The initial state is that a task has not |
---|
157 | executed and thus has consumed no CPU time. default state which is when |
---|
158 | zero period executions have occurred. |
---|
159 | |
---|
160 | NOTES: |
---|
161 | NONE |
---|