From e694c94bf7221d94232743eb162c227975cd91e8 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 14 Sep 2006 15:06:38 +0000 Subject: 2006-09-14 Joel Sherrill * new_chapters/Makefile.am, new_chapters/gen_section, new_chapters/new_chapters.texi, user/Makefile.am, user/c_user.texi, user/dirstat.texi: Promote CPU Usage to first class citizen. Rename to start with rtems_ and include documentation in user guide. * user/cpuuse.t: New file. * new_chapters/cpuuse.t: Removed. --- doc/user/Makefile.am | 13 +++-- doc/user/c_user.texi | 2 + doc/user/cpuuse.t | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/user/dirstat.texi | 2 +- 4 files changed, 155 insertions(+), 5 deletions(-) create mode 100644 doc/user/cpuuse.t (limited to 'doc/user') diff --git a/doc/user/Makefile.am b/doc/user/Makefile.am index 8aaf34c041..ec51b764c8 100644 --- a/doc/user/Makefile.am +++ b/doc/user/Makefile.am @@ -18,7 +18,7 @@ GENERATED_FILES = overview.texi concepts.texi datatypes.texi init.texi \ task.texi intr.texi clock.texi timer.texi sem.texi msg.texi event.texi \ signal.texi part.texi region.texi dpmem.texi io.texi fatal.texi \ schedule.texi rtmon.texi bsp.texi userext.texi conf.texi mp.texi \ - stackchk.texi + stackchk.texi cpuuse.texi COMMON_FILES += $(top_srcdir)/common/cpright.texi @@ -161,12 +161,17 @@ mp.texi: mp.t stackchk.texi: stackchk.t $(BMENU2) -p "Multiprocessing Manager MULTIPROCESSING_ANNOUNCE - Announce the arrival of a packet" \ + -u "Top" \ + -n "CPU Usage Statistics" < $< > $@ + +cpuuse.texi: cpuuse.t + $(BMENU2) -p "Stack Bounds Checker stack_checker_dump_usage - Report Task Stack Usage" \ -u "Top" \ -n "Directive Status Codes" < $< > $@ -EXTRA_DIST = bsp.t concepts.t clock.t datatypes.t conf.t dpmem.t event.t \ - fatal.t init.t intr.t io.t mp.t msg.t overview.t part.t region.t rtmon.t \ - sem.t schedule.t signal.t stackchk.t task.t timer.t userext.t \ +EXTRA_DIST = bsp.t clock.t concepts.t cpuuse.t datatypes.t conf.t dpmem.t \ + event.t fatal.t init.t intr.t io.t mp.t msg.t overview.t part.t region.t \ + rtmon.t sem.t schedule.t signal.t stackchk.t task.t timer.t userext.t \ $(TXT_FILES) $(PNG_FILES) $(EPS_IMAGES) $(noinst_DATA) CLEANFILES += c_user.info c_user.info-? c_user.info-?? diff --git a/doc/user/c_user.texi b/doc/user/c_user.texi index 3336c1dae5..8a20a6dfc4 100644 --- a/doc/user/c_user.texi +++ b/doc/user/c_user.texi @@ -101,6 +101,7 @@ @include conf.texi @include mp.texi @include stackchk.texi +@include cpuuse.texi @include dirstat.texi @include example.texi @include glossary.texi @@ -136,6 +137,7 @@ This is the online version of the RTEMS C User's Guide. * Configuring a System:: * Multiprocessing Manager:: * Stack Bounds Checker:: +* CPU Usage Statistics:: * Directive Status Codes:: * Example Application:: * Glossary:: diff --git a/doc/user/cpuuse.t b/doc/user/cpuuse.t new file mode 100644 index 0000000000..161df741cd --- /dev/null +++ b/doc/user/cpuuse.t @@ -0,0 +1,143 @@ +@c +@c COPYRIGHT (c) 1988-2002. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. +@c +@c $Id$ +@c + +@chapter CPU Usage Statistics + +@section Introduction + +The CPU usage statistics manager is an RTEMS support +component that provides a convenient way to manipulate +the CPU usage information associated with each task +The routines provided by the CPU usage statistics manager are: + +@itemize @bullet +@item @code{@value{DIRPREFIX}cpu_usage_report} - Report CPU Usage Statistics +@item @code{@value{DIRPREFIX}cpu_usage_reset} - Reset CPU Usage Statistics +@end itemize + +@section Background + +@section Operations + +@section Report CPU Usage Statistics + +@subsection Reporting Period Statistics + +The application may dynamically report the CPU usage for every +task in the system by calling the +@code{@value{DIRPREFIX}cpu_usage_report} routine. +This routine prints a table with the following information per task: + +@itemize @bullet +@item task id +@item task name +@item number of clock ticks executed +@item percentage of time consumed by this task +@end itemize + +The following is an example of the report generated: + +@example +@group +CPU Usage by thread + ID NAME TICKS PERCENT +0x04010001 IDLE 0 0.000 +0x08010002 TA1 1203 0.748 +0x08010003 TA2 203 0.126 +0x08010004 TA3 202 0.126 + +Ticks since last reset = 1600 + +Total Units = 1608 +@end group +@end example + +Notice that the "Total Units" is greater than the ticks per reset. +This is an artifact of the way in which RTEMS keeps track of CPU +usage. When a task is context switched into the CPU, the number +of clock ticks it has executed is incremented. While the task +is executing, this number is incremented on each clock tick. +Otherwise, if a task begins and completes execution between +successive clock ticks, there would be no way to tell that it +executed at all. + +Another thing to keep in mind when looking at idle time, is that +many systems -- especially during debug -- have a task providing +some type of debug interface. It is usually fine to think of the +total idle time as being the sum of the IDLE task and a debug +task that will not be included in a production build of an application. + +@section Reset CPU Usage Statistics + +Invoking the @code{@value{DIRPREFIX}cpu_usage_reset} routine resets +the CPU usage statistics for all tasks in the system. + +@section Directives + +This section details the CPU usage statistics manager's directives. +A subsection is dedicated to each of this manager's directives +and describes the calling sequence, related constants, usage, +and status codes. + +@page +@subsection cpu_usage_report - Report CPU Usage Statistics + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +void rtems_cpu_usage_report( void ); +@end example +@end ifset + +@ifset is-Ada +@example +An Ada interface is not currently available. +@end example +@end ifset + +@subheading STATUS CODES: NONE + +@subheading DESCRIPTION: + +This routine prints out a table detailing the CPU usage statistics for +all tasks in the system. + +@subheading NOTES: + +NONE + +@page +@subsection cpu_usage_reset - Reset CPU Usage Statistics + +@subheading CALLING SEQUENCE: + +@ifset is-C +@example +void rtems_cpu_usage_reset( void ); +@end example +@end ifset + +@ifset is-Ada +@example +An Ada interface is not currently available. +@end example +@end ifset + +@subheading STATUS CODES: NONE + +@subheading DESCRIPTION: + +This routine re-initializes the CPU usage statistics for all tasks +in the system to their initial state. The initial state is that +a task has not executed and thus has consumed no CPU time. +default state which is when zero period executions have occurred. + +@subheading NOTES: + +NONE diff --git a/doc/user/dirstat.texi b/doc/user/dirstat.texi index e7576e40e6..b1ac891d22 100644 --- a/doc/user/dirstat.texi +++ b/doc/user/dirstat.texi @@ -7,7 +7,7 @@ @c @ifinfo -@node Directive Status Codes, Example Application, Stack Bounds Checker stack_checker_dump_usage - Report Task Stack Usage, Top +@node Directive Status Codes, Example Application, CPU Usage Statistics cpu_usage_reset - Reset CPU Usage Statistics, Top @end ifinfo @chapter Directive Status Codes @table @b -- cgit v1.2.3