lkml.org 
[lkml]   [2012]   [Dec]   [15]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
From
Date
SubjectRe: man page for s390_runtime_instr syscall
Hello Jan,

On Mon, Dec 10, 2012 at 12:34 PM, Jan Glauber <jang@linux.vnet.ibm.com> wrote:
> Hi Michael,
>
> I've written a man page for the s390_runtime_instr syscall which was
> merged with 3.7 (e4b8b3f). Now the question is if you would like to
> include it in the man-pages although it is completely s390 specific
and wont be available on any other arch? Or should it go into a
> different package?

Thanks for this page. The man-pages package is the right place for it,
but a few things need fixing. Could you see below and resubmit please?

> --- /dev/null 2012-12-04 10:52:46.657720288 +0100
> +++ s390_runtime_instr.2 2012-10-09 13:55:39.000000000 +0200
> @@ -0,0 +1,73 @@
> +.\" Copyright IBM Corp. 2012
> +.\" Author: Jan Glauber <jang@linux.vnet.ibm.com>

You have provided no license here. Can you please add one. Please see
http://www.kernel.org/doc/man-pages/licenses.html. (My preference is
the "verbatim" license, but others are of course possible.)

> +.\"
> +.TH S390_RUNTIME_INSTR 2 2012-10-09 "Linux Programmer's Manual"

Update the date here.

> +.SH NAME
> +s390_runtime_instr \- enable/disable s390 CPU runtime instrumentation
> +.SH SYNOPSIS
> +.nf
> +.B #include <asm/runtime_instr.h>
> +
> +.BI "int s390_runtime_instr(int " command ", int " signum ");
> +.fi
> +
> +.SH DESCRIPTION
> +The
> +.BR s390_runtime_instr ()
> +system call starts or stops CPU runtime instrumentation for the current thread.
> +
> +The
> +.IR command
> +argument controls whether runtime instumentation is started

Spelling: instrumentation

> +( 1 ) or stopped ( 2 ) for the current thread.
> +
> +The
> +.IR signum
> +argument specifies the number of a real-time signal. The

Please start new sentences on a new source line.

> +real-time signal is sent to the thread if the runtime instrumentation
> +buffer is full or if the runtime-instrumentation-halted interrupt
> +occured.

Spelling: occurred.

> +
> +.SH RETURN VALUE
> +On success
> +.BR s390_runtime_instr ()
> +returns 0 and enables the thread for
> +runtime instrumentation by assigning the thread a default runtime
> +instrumentation control block. The caller can then read and modify the

Start new sentence on a new source line.

> +control block and start the runtime instrumentation. On error, -1 is

Start new sentence on a new source line.

> +returned and
> +.IR errno
> +is set to one of the error codes listed below.
> +
> +.SH ERRORS
> +.TP
> +.B EOPNOTSUPP
> +The runtime instrumentation facility is not available.
> +.TP
> +.B EINVAL
> +The value specified in
> +.IR command
> +is not a valid command or the value specified in
> +.IR signum
> +is not a real-time signal number.
> +.TP
> +.B ENOMEM
> +Allocating memory for the runtime instrumentation control block
> +failed.
> +
> +.SH VERSIONS
> +This system call is available since Linux 3.7.
> +
> +.SH CONFORMING TO
> +This system call

This Linux-specific system call

> +is only available on the s390 architecture. The runtime instrumentation facility is available

http://www.kernel.org/doc/man-pages/licenses.html

> +beginning with System z EC12.
> +
> +.SH NOTES
> +Glibc does not provide a wrapper for this system call, use
> +.BR syscall (2)
> +to call it.

Somewhere around here it would be nice to have some notes on how one
uses this RI feature. The commit
e4b8b3f33fcaa0ed6e6b5482a606091d8cd20beb has a bit of info. I'd
suggest including that info in the page, with (possibly) an example.

> +
> +.SH SEE ALSO
> +.BR signal (7),
> +.BR syscall (2)

Order entries here by section number.

Thanks,

Michael


--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/


\
 
 \ /
  Last update: 2012-12-15 20:21    [W:0.055 / U:0.040 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site