[PATCH] man page for pip_stress

[PATCH] man page for pip_stress

[Uwe Kleine-König]

The Debian package checker lintian criticizes that pip_stress doesn't have a
man page. So put a short version of the description from the source file
into a man page to make lintian happy.

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
Hello Clark,

you can pull this branch and the buffer overflow fix from

	git://git.pengutronix.de/git/ukl/rt-tests.git for-clark

Best regards
Uwe

 Makefile                  |    1 +
 src/pi_tests/pip_stress.8 |   25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 0 deletions(-)
 create mode 100644 src/pi_tests/pip_stress.8

diff --git a/Makefile b/Makefile
index 48bef8a..2dd065f 100644
--- a/Makefile
+++ b/Makefile
@@ -122,6 +122,7 @@ install: all
 	gzip src/backfire/backfire.4 -c >"$(DESTDIR)$(mandir)/man4/backfire.4.gz"
 	gzip src/cyclictest/cyclictest.8 -c >"$(DESTDIR)$(mandir)/man8/cyclictest.8.gz"
 	gzip src/pi_tests/pi_stress.8 -c >"$(DESTDIR)$(mandir)/man8/pi_stress.8.gz"
+	gzip src/pi_tests/pip_stress.8 -c >"$(DESTDIR)$(mandir)/man8/pip_stress.8.gz"
 	gzip src/hwlatdetect/hwlatdetect.8 -c >"$(DESTDIR)$(mandir)/man8/hwlatdetect.8.gz"
 	gzip src/ptsematest/ptsematest.8 -c >"$(DESTDIR)$(mandir)/man8/ptsematest.8.gz"
 	gzip src/sigwaittest/sigwaittest.8 -c >"$(DESTDIR)$(mandir)/man8/sigwaittest.8.gz"
diff --git a/src/pi_tests/pip_stress.8 b/src/pi_tests/pip_stress.8
new file mode 100644
index 0000000..b733335
--- /dev/null
+++ b/src/pi_tests/pip_stress.8
@@ -0,0 +1,25 @@
+.TH pip_stress 8 2011-06-24
+.SH NAME
+pip_stress \- test priority inheritance between processes
+.SH SYNOPSIS
+.B pip_stress
+.SH DESCRIPTION
+.B pip_stress
+creates a priority inversion using three processes and a priority inheritance
+mutex shared via shared memory.
+All three processes are bound to run on the same cpu.
+The process with the lowest priority holds a mutex and is prempted by the
+medium priority process that just runs an infinite loop.
+The third process with the highest priority tries to grab the mutex that is
+hold by the low prio process.
+As a priority inheritance mutex is used the low priority process lends the high
+priority process' priority to unlock the mutex and so stops the medium priority
+process blocking the high priority one.
+
+.B pip_stress
+doesn't take any options and quits as soon as the priority inversion is
+resolved which should happen instantly.
+
+.SH AUTHOR
+.B pip_stress
+was written by John Kacur <jkacur@redhat.com>.
-- 
1.7.5.4

--
To unsubscribe from this list: send the line "unsubscribe linux-rt-users" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] man page for pip_stress

[John Kacur]

----- Original Message -----
> The Debian package checker lintian criticizes that pip_stress doesn't
> have a
> man page. So put a short version of the description from the source
> file
> into a man page to make lintian happy.
> 

Why not just steal the text in the comments at the top of the file and put that into man page form?

Thanks

John

Re: [PATCH] man page for pip_stress

[Uwe Kleine-König]

Hi John,

On Mon, Jun 27, 2011 at 09:11:45AM -0400, John Kacur wrote:
> ----- Original Message -----
> > The Debian package checker lintian criticizes that pip_stress doesn't
> > have a
> > man page. So put a short version of the description from the source
> > file
> > into a man page to make lintian happy.
> > 
> 
> Why not just steal the text in the comments at the top of the file and
> put that into man page form?
I reread the description in pip_stress.c and I think it is too verbose
for a manpage. A few examples that are IMHO not suitable for a man page:

	Pay particular attention to how this [mmap to back the
	pthread_mutex_t] is intialized to support processes.

	The state structure keeps track of the progress.

	In either case this program demonstrates how to use priority
	inheritance mutexes with processes.

	If you are having difficulty triggering an inversion, merely
	increase the time that the low priority process sleeps while
	holding the lock.

These are good as comments in the source file but are not helpful for a
user who just wants to use pip_stress.
	
Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
--
To unsubscribe from this list: send the line "unsubscribe linux-rt-users" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html