Commit d40d48e1 authored by Daniel Bristot de Oliveira's avatar Daniel Bristot de Oliveira Committed by Steven Rostedt
Browse files

rtla: Add Documentation 

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.

Link: https://lkml.kernel.org/r/5f510f3e962fc0cd531c43f5a815544dd720c3f2.1639158831.git.bristot@kernel.org



Cc: Tao Zhou <tao.zhou@linux.dev>
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: default avatarSteven Rostedt <rostedt@goodmis.org>
Suggested-by: default avatarJonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarDaniel Bristot de Oliveira <bristot@kernel.org>
Signed-off-by: default avatarSteven Rostedt <rostedt@goodmis.org>
parent 1eeb6328

Documentation/tools/rtla/Makefile

0 → 100644
+41 −0
Original line number Diff line number Diff line 
# 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

Documentation/tools/rtla/common_appendix.rst

0 → 100644
+12 −0
Original line number Diff line number Diff line 
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).

Documentation/tools/rtla/rtla.rst

0 → 100644
+48 −0
Original line number Diff line number Diff line 
=========

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

tools/tracing/rtla/Makefile

+26 −4
Original line number Diff line number Diff line
@@ -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,7 +76,7 @@ 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
@@ -76,5 +86,17 @@ 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