[rtems-central commit] spec: Specify CPU usage reporting
Sebastian Huber
sebh at rtems.org
Mon Oct 4 11:43:18 UTC 2021
Module: rtems-central
Branch: master
Commit: d85282c0e21bbf3d84296aef2e55728049a61fd2
Changeset: http://git.rtems.org/rtems-central/commit/?id=d85282c0e21bbf3d84296aef2e55728049a61fd2
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Fri Oct 1 15:58:28 2021 +0200
spec: Specify CPU usage reporting
---
config.yml | 1 +
spec/c/if/getchar.yml | 16 ++++++
spec/rtems/cpuuse/if/cpu-info-report.yml | 38 +++++++++++++++
spec/rtems/cpuuse/if/group.yml | 21 ++++++++
spec/rtems/cpuuse/if/header.yml | 16 ++++++
spec/rtems/cpuuse/if/printer.yml | 12 +++++
spec/rtems/cpuuse/if/report-with-plugin.yml | 39 +++++++++++++++
spec/rtems/cpuuse/if/report.yml | 36 ++++++++++++++
spec/rtems/cpuuse/if/reset.yml | 34 +++++++++++++
spec/rtems/cpuuse/if/top-with-plugin.yml | 41 ++++++++++++++++
spec/rtems/cpuuse/if/top.yml | 36 ++++++++++++++
spec/rtems/cpuuse/req/reset.yml | 15 ++++++
spec/rtems/cpuuse/val/cpuuse.yml | 75 +++++++++++++++++++++++++++++
spec/rtems/ratemon/req/get-status.yml | 6 ++-
14 files changed, 385 insertions(+), 1 deletion(-)
diff --git a/config.yml b/config.yml
index a349b2b..a3314af 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 0000000..4dbe0cc
--- /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 0000000..326d74f
--- /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 0000000..94bce7c
--- /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 0000000..2df87b4
--- /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 0000000..915f003
--- /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 0000000..dd5cb6b
--- /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 0000000..bf36999
--- /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 0000000..43b7ff6
--- /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 0000000..3eac6e2
--- /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 0000000..338e309
--- /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 0000000..b6e84b3
--- /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 0000000..82198ae
--- /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, ×tamp );
+ T_gt_i64( timestamp, 0 );
+
+ _Thread_Get_CPU_time_used( other, ×tamp );
+ 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, ×tamp );
+ T_eq_i64( timestamp, 4295 );
+
+ _Thread_Get_CPU_time_used( other, ×tamp );
+ 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 1939799..d5afc55 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
More information about the vc
mailing list