Skip to contentSkip to conversation

add tracepoints docbook (take #2)

PATCH In review Jason Baron 2 participants 9 messages Apr 30, 2009 – May 1, 2009

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover add tracepoints docbook (take #2)

The following patches add a new tracepoint docbook. Since tracepoints can be defined by various macros and in various files, I think it important to clearly document the available tracepoints, as Andrew has pointed out. This helps us see what we have and what we don't have. If this patch is accepted, I hope that others will add docbook style comments, so we can have a complete accounting of the kernel's tracepoints.

The docbook from these patch series can be viewed at:
http://people.redhat.com/~jbaron/tracepoints/

thanks,

-Jason

Jason Baron (3):
-make kernel-doc understand TRACE_EVENT() macro
-add new tracepoints docbook
-add irq tracepoint documentation

 Documentation/DocBook/Makefile        |    3 +-
 Documentation/DocBook/tracepoint.tmpl |   89 +++++++++++++++++++++++++++++++++
 include/trace/events/irq.h            |   46 +++++++++++++++--
 scripts/kernel-doc                    |   22 ++++++++
 4 files changed, 155 insertions(+), 5 deletions(-)
 create mode 100644 Documentation/DocBook/tracepoint.tmpl
#1 lore raw

PATCH 1/3 make kernel-doc understand TRACE_EVENT() macro (take #2)

Add support to kernel-doc for tracepoint comments above TRACE_EVENT() macro definitions. Paves the way for tracepoint docbook.

---
 scripts/kernel-doc |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)
scripts/kernel-doc +22 -0
index 0f11870..2b53a55 100755
@@ -1827,6 +1827,25 @@ sub reset_state {
     $state = 0;
 }
 
+sub tracepoint_munge($) {
+	my $file = shift;
+	my $tracepointname = 0;
+	my $tracepointargs = 0;
+
+	if($prototype =~ m/TRACE_EVENT\((.*?),/) {
+		$tracepointname = $1;
+	}
+	if($prototype =~ m/TP_PROTO\((.*?)\)/) {
+		$tracepointargs = $1;
+	}
+	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
+		print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
+			     "$prototype\n";
+	} else {
+		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+	}
+}
+
 sub syscall_munge() {
 	my $void = 0;
 
@@ -1881,6 +1900,9 @@ sub process_state3_function($$) {
 	if ($prototype =~ /SYSCALL_DEFINE/) {
 		syscall_munge();
 	}
+	if ($prototype =~ /TRACE_EVENT/) {
+		tracepoint_munge($file);
+	}
 	dump_function($prototype, $file);
 	reset_state();
     }
Signature · 1 line
1.6.0.6
#2 lore raw

[tip:tracing/core] kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)

Commit-ID:  56afb0f8823650f53a5f0e96d69a282e8892c61b
Gitweb:     http://git.kernel.org/tip/56afb0f8823650f53a5f0e96d69a282e8892c61b
Author:     Jason Baron <[email protected]>
AuthorDate: Thu, 30 Apr 2009 13:29:36 -0400
Committer:  Ingo Molnar <[email protected]>
CommitDate: Fri, 1 May 2009 14:03:35 +0200

kerneldoc, tracing: make kernel-doc understand TRACE_EVENT() macro (take #2)

Add support to kernel-doc for tracepoint comments above TRACE_EVENT() macro definitions. Paves the way for tracepoint docbook.

[ Impact: extend DocBook infrastructure ]

LKML-Reference: <d80706b6797e277924d2f3ec9af176c6b2951f88.1241107197.git.jbaron@redhat.com>

---
 scripts/kernel-doc |   22 ++++++++++++++++++++++
 1 files changed, 22 insertions(+), 0 deletions(-)
scripts/kernel-doc +22 -0
index 0f11870..2b53a55 100755
@@ -1827,6 +1827,25 @@ sub reset_state {
     $state = 0;
 }
 
+sub tracepoint_munge($) {
+	my $file = shift;
+	my $tracepointname = 0;
+	my $tracepointargs = 0;
+
+	if($prototype =~ m/TRACE_EVENT\((.*?),/) {
+		$tracepointname = $1;
+	}
+	if($prototype =~ m/TP_PROTO\((.*?)\)/) {
+		$tracepointargs = $1;
+	}
+	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
+		print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
+			     "$prototype\n";
+	} else {
+		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
+	}
+}
+
 sub syscall_munge() {
 	my $void = 0;
 
@@ -1881,6 +1900,9 @@ sub process_state3_function($$) {
 	if ($prototype =~ /SYSCALL_DEFINE/) {
 		syscall_munge();
 	}
+	if ($prototype =~ /TRACE_EVENT/) {
+		tracepoint_munge($file);
+	}
 	dump_function($prototype, $file);
 	reset_state();
     }
#3 lore raw

PATCH 2/3 add new tracepoints docbook (take #2)

In reply to Jason Baron

Add tracepoint docbook. This will help us document and understand what tracepoints are in the kernel. Since there are multiple macros, and files that contain tracepoints.

---
 Documentation/DocBook/Makefile        |    3 +-
 Documentation/DocBook/tracepoint.tmpl |   84 +++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/DocBook/tracepoint.tmpl
Documentation/DocBook/Makefile +2 -1
index 8918a32..4c8f4d6 100644
@@ -13,7 +13,8 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
 	    mac80211.xml debugobjects.xml sh.xml regulator.xml \
-	    alsa-driver-api.xml writing-an-alsa-driver.xml
+	    alsa-driver-api.xml writing-an-alsa-driver.xml \
+	    tracepoint.xml
 
 ###
 # The build process is as follows (targets):
Documentation/DocBook/tracepoint.tmpl new file +84 -0

84 lines not on this page · raw message

Signature · 1 line
1.6.0.6
#4 lore raw

[tip:tracing/core] tracing: add new tracepoints docbook

Commit-ID:  a76f8c6da1e48fd4ef025f42c736389532ff30ba
Gitweb:     http://git.kernel.org/tip/a76f8c6da1e48fd4ef025f42c736389532ff30ba
Author:     Jason Baron <[email protected]>
AuthorDate: Thu, 30 Apr 2009 13:29:42 -0400
Committer:  Ingo Molnar <[email protected]>
CommitDate: Fri, 1 May 2009 14:03:35 +0200

tracing: add new tracepoints docbook

Add tracepoint docbook. This will help us document and understand what tracepoints are in the kernel. Since there are multiple macros, and files that contain tracepoints.

[ Impact: add documentation ]

LKML-Reference: <84160b6bd94aff02455da7e12bad054d34c579a0.1241107197.git.jbaron@redhat.com>

---
 Documentation/DocBook/Makefile        |    3 +-
 Documentation/DocBook/tracepoint.tmpl |   84 +++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+), 1 deletions(-)
Documentation/DocBook/Makefile +2 -1
index 8918a32..4c8f4d6 100644
@@ -13,7 +13,8 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
 	    mac80211.xml debugobjects.xml sh.xml regulator.xml \
-	    alsa-driver-api.xml writing-an-alsa-driver.xml
+	    alsa-driver-api.xml writing-an-alsa-driver.xml \
+	    tracepoint.xml
 
 ###
 # The build process is as follows (targets):
Documentation/DocBook/tracepoint.tmpl new file +84 -0

84 lines not on this page · raw message

#5 lore raw

PATCH 3/3 add irq tracepoint documentation (take #2)

In reply to Jason Baron

Document irqs for the newly created docbook.

---
 Documentation/DocBook/tracepoint.tmpl |    5 +++
 include/trace/events/irq.h            |   46 ++++++++++++++++++++++++++++++---
 2 files changed, 47 insertions(+), 4 deletions(-)
Documentation/DocBook/tracepoint.tmpl +5 -0
index 70891bc..b0756d0 100644
@@ -81,4 +81,9 @@
    </para>
   </chapter>
 
+  <chapter id="irq">
+   <title>IRQ</title>
+!Iinclude/trace/events/irq.h
+  </chapter>
+
 </book>
include/trace/events/irq.h +42 -4

70 lines not on this page · raw message

Signature · 1 line
1.6.0.6
#6 lore raw

[tip:tracing/core] tracing: add irq tracepoint documentation

Commit-ID:  9ee1983c9aa18f12388ef660d0c76a23dc112959
Gitweb:     http://git.kernel.org/tip/9ee1983c9aa18f12388ef660d0c76a23dc112959
Author:     Jason Baron <[email protected]>
AuthorDate: Thu, 30 Apr 2009 13:29:47 -0400
Committer:  Ingo Molnar <[email protected]>
CommitDate: Fri, 1 May 2009 14:03:36 +0200

tracing: add irq tracepoint documentation

Document irqs for the newly created docbook.

[ Impact: add documentation ]

LKML-Reference: <73ff42be3420157667ec548e9b0e409c3cfad05f.1241107197.git.jbaron@redhat.com>

---
 Documentation/DocBook/tracepoint.tmpl |    5 +++
 include/trace/events/irq.h            |   46 ++++++++++++++++++++++++++++++---
 2 files changed, 47 insertions(+), 4 deletions(-)
Documentation/DocBook/tracepoint.tmpl +5 -0
index 70891bc..b0756d0 100644
@@ -81,4 +81,9 @@
    </para>
   </chapter>
 
+  <chapter id="irq">
+   <title>IRQ</title>
+!Iinclude/trace/events/irq.h
+  </chapter>
+
 </book>
include/trace/events/irq.h +42 -4

70 lines not on this page · raw message

#7 lore raw
In reply to Jason Baron
Quoted 7 lines · Jason Baron

The following patches add a new tracepoint docbook. Since tracepoints can be defined by various macros and in various files, I think it important to clearly document the available tracepoints, as Andrew has pointed out. This helps us see what we have and what we don't have. If this patch is accepted, I hope that others will add docbook style comments, so we can have a complete accounting of the kernel's tracepoints.

hi,

i'd also like to get some agreement that future tracepoints need to have this sort of documentation included when they are submitted. Also, I'd like people who have already submitted tracepoints to go back and add this kind of documentation. I'll volunteer to police the effort if we agree it should be done.

thanks,

-Jason

#8 lore raw
Quoted 11 lines · Jason Baron
Quoted 8 lines · Jason Baron

The following patches add a new tracepoint docbook. Since tracepoints can be defined by various macros and in various files, I think it important to clearly document the available tracepoints, as Andrew has pointed out. This helps us see what we have and what we don't have. If this patch is accepted, I hope that others will add docbook style comments, so we can have a complete accounting of the kernel's tracepoints.

Quoted 7 lines

hi,

i'd also like to get some agreement that future tracepoints need to have this sort of documentation included when they are submitted. Also, I'd like people who have already submitted tracepoints to go back and add this kind of documentation. I'll volunteer to police the effort if we agree it should be done.

sure - but sending patches would be even more useful than policing :)

Ingo