rteval: Modernize documentation
PATCH 1/2 rteval: Modernize documentation
Update and reorganize rteval documentation:
- Completely rewrite rteval.8 man page with current options and features
- Add comprehensive sections for all measurement modules (cyclictest and timerlat)
- Add all cpuset, load control, and configuration options
- Include practical examples section
- Update to reflect current rteval 3.10 functionality
- Update README with modern installation and dependency information
- Add sysstat, rtla, and all build tool dependencies
- Organize dependencies by category (measurement, load modules, utilities)
- Use HTTPS URLs instead of deprecated git:// protocol
- Update TESTING section with current test targets
- Rename doc/rteval.txt to doc/rteval-legacy.txt to indicate it's historical
- Delete doc/installing.txt as redundant with README
- Add SPDX-License-Identifier to all documentation files
---
README | 122 ++++++--
doc/installing.txt | 23 --
doc/{rteval.txt => rteval-legacy.txt} | 2 +
doc/rteval.8 | 398 +++++++++++++++++---------
4 files changed, 367 insertions(+), 178 deletions(-)
delete mode 100644 doc/installing.txt
rename doc/{rteval.txt => rteval-legacy.txt} (99%)README +95 -27
@@ -1,42 +1,110 @@ +SPDX-License-Identifier: GPL-2.0-or-later -Rteval is a python program written to evaluate the performance of a +Rteval is a Python program written to evaluate the performance of a realtime Linux kernel on a particular hardware platform. The program -unpacks source code for two loads: hackbench and a Linux kernel -compile, then loops running hackbench and a parallel build of the -Linux kernel. While the loads are running, the cyclictest program is -run to measure realtime performance under load. When the specified run -duration is met, the loads are stopped and cyclictest outputs measured -timer latency values in histogram format, which is analyzed by -rteval. Rteval then writes an XML file to disk with information about -the system (gotten through DMI tables), the raw histogram data -collected during the run and the statistical analysis of the run. +runs measurement modules (cyclictest or timerlat) to measure scheduling +and timer latency while simultaneously running system load modules +(kernel compile, hackbench, stress-ng) to stress the system. -The rteval source may be pulled from it's git tree on kernel.org: - git://git.kernel.org/pub/scm/utils/rteval/rteval.git +When the specified run duration is met, rteval stops the loads and +measurements, then writes an XML report to disk with information about +the system (from DMI tables), raw measurement data, and statistical +analysis including min/max latency, standard deviation, and histograms. -Rteval requires the following packages to run: +INSTALLATION +============ + +The rteval source may be pulled from its git tree on kernel.org: + https://git.kernel.org/pub/scm/utils/rteval/rteval.git + +Required Dependencies: Python >= 3.8 - http://www.python.org/download/ + https://www.python.org/download/ + +python3-lxml + https://lxml.de/ + +python3-libxml2 + https://xmlsoft.org/ + +sysstat + System performance monitoring tools (sar, iostat, mpstat) + +Measurement Module Requirements (choose one): + +For cyclictest measurement module: + rt-tests (realtime-tests package) + https://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git + +For timerlat measurement module (recommended): + rtla (part of Linux kernel tools) + Requires kernel 5.15+ with CONFIG_OSNOISE_TRACER enabled + +Load Module Requirements: + +For kcompile load module: + rteval-loads package (provides kernel source tarballs) + Or manually download kernel sources from https://www.kernel.org/ + + Build tools: gcc, binutils, gcc-c++, make, flex, bison, bc, + kernel-headers, openssl-devel, perl-interpreter, + elfutils-libelf-devel, xz, bzip2, tar, gzip + +For stress-ng load module (optional): + stress-ng + https://github.com/ColinIanKing/stress-ng -python-lxml - http://lxml.de/ +System utilities: + numactl, dmidecode, procps-ng -libxml2-python - http://xmlsoft.org/ +Installation: -rt-tests - git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git + $ git clone https://git.kernel.org/pub/scm/utils/rteval/rteval.git + $ cd rteval + $ sudo make install -Rteval end-to-end tests additionally require the following packages: +For rt-tests (if using cyclictest): -Test::Harness + $ git clone https://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git + $ cd rt-tests + $ sudo make prefix=/usr install + +TESTING +======= + +Rteval includes unit tests and end-to-end tests. End-to-end tests +require: + +Test::Harness (Perl module) https://metacpan.org/pod/Test::Harness -Clark Williams <[email protected]> wrote rteval +Run tests with: + $ make test # Unit tests + $ make e2e-tests # End-to-end tests (requires root) + +USAGE +===== + +Basic usage (requires root): + + $ sudo rteval -d 3600 + +Run with timerlat measurement module: + + $ sudo rteval -d 3600 --measurement-module timerlat + +See the man page for more options: + + $ man rteval + +AUTHORS +======= + +Clark Williams <williams at redhat dot com> wrote rteval. -David Sommerseth <[email protected]> wrote the XML-RPC and database - logic for handling rteval results. +David Sommerseth wrote the XML-RPC and database logic for handling + rteval results. -John Kacur <jkacur at redhat dot com> ported it to python-3.0 - and has been developing and maintaining it since then. +John Kacur <jkacur at redhat dot com> ported it to Python 3 and has + been developing and maintaining it since then.
doc/installing.txt deleted +0 -23
@@ -1,23 +0,0 @@ -The rteval utility requires some external software libraries to run -properly. These are: - -python-lxml - A python library to parse XML files and XSLT stylesheets - http://lxml.de/ - -libxml2-python - A python library to parse XML files - http://xmlsoft.org/ - -rt-tests - A collection of programs used to measure real-time behavior - git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git - - -$ git clone \ - git://git.kernel.org/pub/scm/utils/rt-tests/rt-tests.git -$ cd rt-tests && sudo make prefix=/usr install -$ cd ../rteval -$ sudo make install - -That should do it (I hope).
doc/rteval-legacy.txt renamed from doc/rteval.txt +2 -0
@@ -1,3 +1,5 @@ +SPDX-License-Identifier: GPL-2.0-or-later + Evaluating Realtime Linux system performance with rteval Clark Williams <[email protected]> --------------------------------------------------------
doc/rteval.8 +270 -128
445 lines not on this page · raw message
Signature · 1 line
2.54.0
PATCH 2/2 rteval: Add make uninstall target and fix pyproject.toml license
Add uninstall target to Makefile:
- Removes rteval script from $(PREFIX)/bin
- Removes man page from share/man/man8
- Removes XSL files and load files from share/rteval
- Uninstalls Python package via pip (if installed from make install)
- Preserves /etc/rteval.conf (user may have customized)
- Respects DESTDIR variable for test installations
- Added to help target and .PHONY declarations
Fix pyproject.toml license deprecation warning:
- Change license from table format {text = "GPL-2.0-or-later"} to simple SPDX string "GPL-2.0-or-later"
- Fixes setuptools deprecation warning about project.license format
Add tags to .gitignore to ignore ctags files
--- .gitignore | 1 + Makefile | 26 +++++++++++++++++++++++++- pyproject.toml | 2 +- 3 files changed, 27 insertions(+), 2 deletions(-)
.gitignore +1 -0
@@ -29,3 +29,4 @@ stamp-h1 autom4te.cache/ rteval-[0-9]* local/ +tags
Makefile +25 -1
@@ -94,6 +94,29 @@ rteval-$(VERSION).tar.bz2: mv dist/rteval-$(VERSION).tar.bz2 . rmdir dist +uninstall: + @echo "Uninstalling rteval..." + # Remove the rteval script + rm -f $(DESTDIR)$(PREFIX)/bin/rteval + # Remove man page + rm -f $(DESTDIR)$(PREFIX)/share/man/man8/rteval.8.gz + # Remove XSL files + rm -f $(DATADIR)/rteval/rteval_*.xsl + # Note: Leaving /etc/rteval.conf in place (remove manually if needed) + # Remove load files + rm -rf $(DATADIR)/rteval/loadsource + # Remove rteval data directory if empty + rmdir $(DATADIR)/rteval 2>/dev/null || true + # Uninstall Python package + @if $(PYTHON) -m pip show rteval 2>/dev/null | grep -q "Location: /usr"; then \ + echo "Uninstalling rteval Python package..."; \ + $(PYTHON) -m pip uninstall -y rteval; \ + elif $(PYTHON) -m pip show rteval >/dev/null 2>&1; then \ + echo "rteval found in pip but points to source directory (not removing)"; \ + else \ + echo "rteval Python package not found (may have been installed via RPM)"; \ + fi + help: @echo "" @echo "rteval Makefile targets:"
@@ -106,6 +129,7 @@ help: @echo " cpuset-tests: run cpuset integration tests (requires root)" @echo " tarfile: create the source tarball" @echo " install: install rteval locally" + @echo " uninstall: uninstall rteval" @echo " clean: cleanup generated files" @echo " realclean: Same as clean plus directory run" @echo " sysreport: do a short testrun and generate sysreport data"
@@ -121,4 +145,4 @@ tags: cleantags: rm -f tags -.PHONY: tests unit-tests e2e-tests regression-tests cpuset-tests +.PHONY: tests unit-tests e2e-tests regression-tests cpuset-tests uninstall
pyproject.toml +1 -1
@@ -18,7 +18,7 @@ analyzed for standard statistical measurements (i.e mode, median, range, mean, variance and standard deviation) and a report is generated. """, content-type = "text/plain"} requires-python = ">=3.10" -license = {text = "GPL-2.0-or-later"} +license = "GPL-2.0-or-later" dependencies = [ "lxml", "requests",
Signature · 1 line
2.54.0