lkml.org 
[lkml]   [2021]   [Nov]   [29]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH V8 08/14] rtla: Add Documentation
    Date
    Adds the basis for rtla documentation. This patch also
    includes the rtla(1) man page.

    As suggested by Jonathan Corbet, we are placing these man
    pages at Documentation/tools/rtla, using rst format. It
    is not linked to the official documentation, though.

    The Makefile is based on bpftool's Documentation one.

    Cc: Steven Rostedt <rostedt@goodmis.org>
    Cc: Ingo Molnar <mingo@redhat.com>
    Cc: Tom Zanussi <zanussi@kernel.org>
    Cc: Masami Hiramatsu <mhiramat@kernel.org>
    Cc: Juri Lelli <juri.lelli@redhat.com>
    Cc: Clark Williams <williams@redhat.com>
    Cc: John Kacur <jkacur@redhat.com>
    Cc: Peter Zijlstra <peterz@infradead.org>
    Cc: Thomas Gleixner <tglx@linutronix.de>
    Cc: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
    Cc: Daniel Bristot de Oliveira <bristot@kernel.org>
    Cc: linux-rt-users@vger.kernel.org
    Cc: linux-trace-devel@vger.kernel.org
    Cc: linux-kernel@vger.kernel.org
    Suggested-by: Steven Rostedt <rostedt@goodmis.org>
    Suggested-by: Jonathan Corbet <corbet@lwn.net>
    Signed-off-by: Daniel Bristot de Oliveira <bristot@kernel.org>
    ---
    Documentation/tools/rtla/Makefile | 41 +++++++++++++++++
    Documentation/tools/rtla/common_appendix.rst | 12 +++++
    Documentation/tools/rtla/rtla.rst | 48 ++++++++++++++++++++
    tools/tracing/rtla/Makefile | 30 ++++++++++--
    4 files changed, 127 insertions(+), 4 deletions(-)
    create mode 100644 Documentation/tools/rtla/Makefile
    create mode 100644 Documentation/tools/rtla/common_appendix.rst
    create mode 100644 Documentation/tools/rtla/rtla.rst

    diff --git a/Documentation/tools/rtla/Makefile b/Documentation/tools/rtla/Makefile
    new file mode 100644
    index 000000000000..9f2b84af1a6c
    --- /dev/null
    +++ b/Documentation/tools/rtla/Makefile
    @@ -0,0 +1,41 @@
    +# SPDX-License-Identifier: GPL-2.0-only
    +# Based on bpftool's Documentation Makefile
    +
    +INSTALL ?= install
    +RM ?= rm -f
    +RMDIR ?= rmdir --ignore-fail-on-non-empty
    +
    +PREFIX ?= /usr/share
    +MANDIR ?= $(PREFIX)/man
    +MAN1DIR = $(MANDIR)/man1
    +
    +MAN1_RST = $(wildcard rtla*.rst)
    +
    +_DOC_MAN1 = $(patsubst %.rst,%.1,$(MAN1_RST))
    +DOC_MAN1 = $(addprefix $(OUTPUT),$(_DOC_MAN1))
    +
    +RST2MAN_DEP := $(shell command -v rst2man 2>/dev/null)
    +RST2MAN_OPTS += --verbose
    +
    +$(OUTPUT)%.1: %.rst
    +ifndef RST2MAN_DEP
    + $(error "rst2man not found, but required to generate man pages")
    +endif
    + rst2man $(RST2MAN_OPTS) $< > $@
    +
    +man1: $(DOC_MAN1)
    +man: man1
    +
    +clean:
    + $(RM) $(DOC_MAN1)
    +
    +install: man
    + $(INSTALL) -d -m 755 $(DESTDIR)$(MAN1DIR)
    + $(INSTALL) -m 644 $(DOC_MAN1) $(DESTDIR)$(MAN1DIR)
    +
    +uninstall:
    + $(RM) $(addprefix $(DESTDIR)$(MAN1DIR)/,$(_DOC_MAN1))
    + $(RMDIR) $(DESTDIR)$(MAN1DIR)
    +
    +.PHONY: man man1 clean install uninstall
    +.DEFAULT_GOAL := man
    diff --git a/Documentation/tools/rtla/common_appendix.rst b/Documentation/tools/rtla/common_appendix.rst
    new file mode 100644
    index 000000000000..b494084acccd
    --- /dev/null
    +++ b/Documentation/tools/rtla/common_appendix.rst
    @@ -0,0 +1,12 @@
    +REPORTING BUGS
    +==============
    +Report bugs to <lkml@vger.kernel.org>
    +
    +LICENSE
    +=======
    +**rtla** is Free Software licensed under the GNU GPLv2
    +
    +COPYING
    +=======
    +Copyright \(C) 2021 Red Hat, Inc. Free use of this software is granted under
    +the terms of the GNU Public License (GPL).
    diff --git a/Documentation/tools/rtla/rtla.rst b/Documentation/tools/rtla/rtla.rst
    new file mode 100644
    index 000000000000..fc0d233efcd5
    --- /dev/null
    +++ b/Documentation/tools/rtla/rtla.rst
    @@ -0,0 +1,48 @@
    +=========
    +rtla
    +=========
    +--------------------------------
    +Real-time Linux Analysis tool
    +--------------------------------
    +
    +:Manual section: 1
    +
    +SYNOPSIS
    +========
    +**rtla** *COMMAND* [*OPTIONS*]
    +
    +DESCRIPTION
    +===========
    +The **rtla** is a meta-tool that includes a set of commands that aims to
    +analyze the real-time properties of Linux. But instead of testing Linux
    +as a black box, **rtla** leverages kernel tracing capabilities to provide
    +precise information about the properties and root causes of unexpected
    +results.
    +
    +COMMANDS
    +========
    +**osnoise**
    +
    + Gives information about the operating system noise (osnoise).
    +
    +**timerlat**
    +
    + Measures the IRQ and thread timer latency.
    +
    +OPTIONS
    +=======
    +**-h**, **--help**
    +
    + Display the help text.
    +
    +For other options, see the man page for the corresponding command.
    +
    +SEE ALSO
    +========
    +**rtla-osnoise**\(1), **rtla-timerlat**\(1)
    +
    +AUTHOR
    +======
    +Daniel Bristot de Oliveira <bristot@kernel.org>
    +
    +.. include:: common_appendix.rst
    diff --git a/tools/tracing/rtla/Makefile b/tools/tracing/rtla/Makefile
    index f254cfbe4fa3..8b9bee124eb3 100644
    --- a/tools/tracing/rtla/Makefile
    +++ b/tools/tracing/rtla/Makefile
    @@ -45,18 +45,28 @@ DATADIR := /usr/share
    DOCDIR := $(DATADIR)/doc
    MANDIR := $(DATADIR)/man
    LICDIR := $(DATADIR)/licenses
    +SRCTREE := $(if $(BUILD_SRC),$(BUILD_SRC),$(CURDIR))
    +
    +# If running from the tarball, man pages are stored in the Documentation
    +# dir. If running from the kernel source, man pages are stored in
    +# Documentation/tools/rtla/.
    +ifneq ($(wildcard Documentation/.*),)
    +DOCSRC = Documentation/
    +else
    +DOCSRC = $(SRCTREE)/../../../Documentation/tools/rtla/
    +endif

    .PHONY: all
    all: rtla

    -rtla: $(OBJ)
    +rtla: $(OBJ) doc
    $(CC) -o rtla $(LDFLAGS) $(OBJ) $(LIBS)

    static: $(OBJ)
    $(CC) -o rtla-static $(LDFLAGS) --static $(OBJ) $(LIBS) -lpthread -ldl

    .PHONY: install
    -install:
    +install: doc_install
    $(INSTALL) -d -m 755 $(DESTDIR)$(BINDIR)
    $(INSTALL) rtla -m 755 $(DESTDIR)$(BINDIR)
    $(STRIP) $(DESTDIR)$(BINDIR)/rtla
    @@ -66,15 +76,27 @@ install:
    ln -s $(DESTDIR)$(BINDIR)/rtla $(DESTDIR)$(BINDIR)/timerlat

    .PHONY: clean tarball
    -clean:
    +clean: doc_clean
    @test ! -f rtla || rm rtla
    @test ! -f rtla-static || rm rtla-static
    @test ! -f src/rtla.o || rm src/rtla.o
    @test ! -f $(TARBALL) || rm -f $(TARBALL)
    @rm -rf *~ $(OBJ) *.tar.$(CEXT)

    -tarball: clean
    +tarball: clean
    rm -rf $(NAME)-$(VERSION) && mkdir $(NAME)-$(VERSION)
    cp -r $(DIRS) $(FILES) $(NAME)-$(VERSION)
    + mkdir $(NAME)-$(VERSION)/Documentation/
    + cp -rp $(SRCTREE)/../../../Documentation/tools/rtla/* $(NAME)-$(VERSION)/Documentation/
    tar $(TAROPTS) --exclude='*~' $(NAME)-$(VERSION)
    rm -rf $(NAME)-$(VERSION)
    +
    +.PHONY: doc doc_clean doc_install
    +doc:
    + $(MAKE) -C $(DOCSRC)
    +
    +doc_clean:
    + $(MAKE) -C $(DOCSRC) clean
    +
    +doc_install:
    + $(MAKE) -C $(DOCSRC) install
    --
    2.31.1
    \
     
     \ /
      Last update: 2021-11-29 12:11    [W:4.260 / U:0.108 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site