spec: Specify CPU usage reporting

14 files changed, 385 insertions, 1 deletions

diff --git a/config.yml b/config.yml
index a349b2b4..a3314af5 100644
--- a/config.yml
+++ b/config.yml
@@ -28,6 +28,7 @@ build:
   - cpukit/doxygen/top-level-groups.h
   - cpukit/libc/string/local.h
   - cpukit/libcsupport/src/malloc_p.h
+  - cpukit/libmisc/cpuuse/cpuuseimpl.h
   - cpukit/libtest/t-test-rtems.h
   - cpukit/score/cpu/sparc/syscall.h
   - cpukit/score/src/opt_compat.h
diff --git a/spec/c/if/getchar.yml b/spec/c/if/getchar.yml
new file mode 100644
index 00000000..4dbe0cc4
--- /dev/null
+++ b/spec/c/if/getchar.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: unspecified-function
+links:
+- role: interface-placement
+  uid: stdio
+- role: interface-ingroup
+  uid: group
+name: getchar
+references:
+- identifier: https://en.cppreference.com/w/c/io/getchar
+  type: url
+type: interface
diff --git a/spec/rtems/cpuuse/if/cpu-info-report.yml b/spec/rtems/cpuuse/if/cpu-info-report.yml
new file mode 100644
index 00000000..326d74fe
--- /dev/null
+++ b/spec/rtems/cpuuse/if/cpu-info-report.yml
@@ -0,0 +1,38 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Reports the CPU information using the printer plugin.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - const ${printer:/name} *${.:/params[0]/name}
+    return: int
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+name: rtems_cpu_info_report
+notes: null
+params:
+- description: |
+    is the printer plugin to output the report.
+  dir: null
+  name: printer
+return:
+  return: |
+    Returns the number of characters printed.
+  return-values: []
+type: interface
diff --git a/spec/rtems/cpuuse/if/group.yml b/spec/rtems/cpuuse/if/group.yml
new file mode 100644
index 00000000..94bce7cd
--- /dev/null
+++ b/spec/rtems/cpuuse/if/group.yml
@@ -0,0 +1,21 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  The CPU usage reporting directives can be used to report and reset the CPU
+  usage of threads.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+description: null
+enabled-by: true
+identifier: libmisc_cpuuse
+index-entries: []
+interface-type: group
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: /if/group
+name: CPU Usage Reporting
+text: |
+  The ${group:/name} shall provide an interface group containing functions to
+  report and reset the CPU usage of threads.
+type: interface
diff --git a/spec/rtems/cpuuse/if/header.yml b/spec/rtems/cpuuse/if/header.yml
new file mode 100644
index 00000000..2df87b44
--- /dev/null
+++ b/spec/rtems/cpuuse/if/header.yml
@@ -0,0 +1,16 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  This header file provides the CPU usage reporting API.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: header-file
+links:
+- role: interface-placement
+  uid: /if/domain
+- role: interface-ingroup
+  uid: group
+path: rtems/cpuuse.h
+prefix: cpukit/include
+type: interface
diff --git a/spec/rtems/cpuuse/if/printer.yml b/spec/rtems/cpuuse/if/printer.yml
new file mode 100644
index 00000000..915f003a
--- /dev/null
+++ b/spec/rtems/cpuuse/if/printer.yml
@@ -0,0 +1,12 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+index-entries: []
+interface-type: forward-declaration
+links:
+- role: interface-placement
+  uid: header
+- role: interface-target
+  uid: ../../io/if/printer
+type: interface
diff --git a/spec/rtems/cpuuse/if/report-with-plugin.yml b/spec/rtems/cpuuse/if/report-with-plugin.yml
new file mode 100644
index 00000000..dd5cb6ba
--- /dev/null
+++ b/spec/rtems/cpuuse/if/report-with-plugin.yml
@@ -0,0 +1,39 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Reports the CPU usage of each thread using the printer plugin.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - const ${printer:/name} *${.:/params[0]/name}
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+name: rtems_cpu_usage_report_with_plugin
+notes: null
+params:
+- description: |
+    is the printer plugin to output the report.
+  dir: null
+  name: printer
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/cpuuse/if/report.yml b/spec/rtems/cpuuse/if/report.yml
new file mode 100644
index 00000000..bf369997
--- /dev/null
+++ b/spec/rtems/cpuuse/if/report.yml
@@ -0,0 +1,36 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Reports the CPU usage of each thread using the ${../../io/if/printk:/name}
+  printer.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+name: rtems_cpu_usage_report
+notes: |
+  See also ${report-with-plugin:/name}.
+params: []
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/cpuuse/if/reset.yml b/spec/rtems/cpuuse/if/reset.yml
new file mode 100644
index 00000000..43b7ff61
--- /dev/null
+++ b/spec/rtems/cpuuse/if/reset.yml
@@ -0,0 +1,34 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Resets the CPU usage of each thread.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+name: rtems_cpu_usage_reset
+notes: null
+params: []
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/cpuuse/if/top-with-plugin.yml b/spec/rtems/cpuuse/if/top-with-plugin.yml
new file mode 100644
index 00000000..3eac6e28
--- /dev/null
+++ b/spec/rtems/cpuuse/if/top-with-plugin.yml
@@ -0,0 +1,41 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Starts an interactive CPU usage reporting using the printer plugin.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - const ${printer:/name} *${.:/params[0]/name}
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: /constraint/request-response
+name: rtems_cpu_usage_top_with_plugin
+notes: |
+  The directive starts a task to do the reporting.  The ${/c/if/getchar:/name}
+  function is used to get commands from the user.
+params:
+- description: |
+    is the printer plugin to output the report.
+  dir: null
+  name: printer
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/cpuuse/if/top.yml b/spec/rtems/cpuuse/if/top.yml
new file mode 100644
index 00000000..338e3096
--- /dev/null
+++ b/spec/rtems/cpuuse/if/top.yml
@@ -0,0 +1,36 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Starts an interactive CPU usage reporting using the
+  ${../../io/if/printk:/name} printer.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params: []
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: /constraint/request-response
+name: rtems_cpu_usage_top
+notes: |
+  See also ${top-with-plugin:/name}.
+params: []
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/cpuuse/req/reset.yml b/spec/rtems/cpuuse/req/reset.yml
new file mode 100644
index 00000000..b6e84b34
--- /dev/null
+++ b/spec/rtems/cpuuse/req/reset.yml
@@ -0,0 +1,15 @@
+SPDX-License-Identifier: CC-BY-SA-4.0
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links:
+- role: interface-function
+  uid: ../if/reset
+functional-type: function
+rationale: null
+references: []
+requirement-type: functional
+text: |
+  When ${../if/reset:/name} is called, the CPU usage shall be set to zero for
+  each thread.
+type: requirement
diff --git a/spec/rtems/cpuuse/val/cpuuse.yml b/spec/rtems/cpuuse/val/cpuuse.yml
new file mode 100644
index 00000000..82198ae8
--- /dev/null
+++ b/spec/rtems/cpuuse/val/cpuuse.yml
@@ -0,0 +1,75 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+links: []
+test-actions:
+- action-brief: |
+    Create a worker thread.  Generate some CPU usage.
+  action-code: |
+    rtems_id          id;
+    Thread_Control   *self;
+    Thread_Control   *other;
+    Timestamp_Control timestamp;
+
+    id = CreateTask( "WORK", GetSelfPriority() );
+    StartTask( id, Worker, NULL );
+
+    self = GetThread( RTEMS_SELF );
+    other = GetThread( id );
+
+    Yield();
+    Yield();
+  checks:
+  - brief: |
+      Check that we have a non-zero CPU usage.  Reset the CPU usage.  Check
+      that it was cleared to zero.
+    code: |
+      _Thread_Get_CPU_time_used( self, &timestamp );
+      T_gt_i64( timestamp, 0 );
+
+      _Thread_Get_CPU_time_used( other, &timestamp );
+      T_gt_i64( timestamp, 0 );
+
+      rtems_cpu_usage_reset();
+
+      /* Our CPU usage is now exactly one tick of the software timecounter */
+      _Thread_Get_CPU_time_used( self, &timestamp );
+      T_eq_i64( timestamp, 4295 );
+
+      _Thread_Get_CPU_time_used( other, &timestamp );
+      T_eq_i64( timestamp, 0 );
+    links:
+    - role: validation
+      uid: ../req/reset
+  - brief: |
+      Clean up all used resources.
+    code: |
+      DeleteTask( id );
+    links: []
+  links: []
+test-brief: |
+  Tests the CPU usage reporting and reset.
+test-context: null
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems/cpuuse.h
+- rtems/score/threadimpl.h
+test-local-includes:
+- tx-support.h
+test-setup: null
+test-stop: null
+test-support: |
+  static void Worker( rtems_task_argument arg )
+  {
+    (void) arg;
+
+    while ( true ) {
+      Yield();
+    }
+  }
+test-target: testsuites/validation/tc-cpuuse.c
+test-teardown: null
+type: test-case
diff --git a/spec/rtems/ratemon/req/get-status.yml b/spec/rtems/ratemon/req/get-status.yml
index 19397991..d5afc55c 100644
--- a/spec/rtems/ratemon/req/get-status.yml
+++ b/spec/rtems/ratemon/req/get-status.yml
@@ -520,7 +520,11 @@ test-support: |
       jobs_count * period_length;
   }
 test-target: testsuites/validation/tc-ratemon-get-status.c
-test-teardown: null
+test-teardown:
+  brief: null
+  code: |
+    SetGetTimecountHandler( ctx->previous_timecounter_handler );
+  description: null
 text: ${.:text-template}
 transition-map:
 - enabled-by: true