From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15474 invoked by alias); 24 Nov 2008 16:48:49 -0000 Received: (qmail 10941 invoked by uid 22791); 24 Nov 2008 16:48:09 -0000 X-Spam-Level: ***** X-Spam-Status: Yes, hits=5.4 required=5.0 tests=AWL,BAYES_50,FR_3TAG_3TAG,HK_OBFDOM,HK_OBFDOMREQ,J_CHICKENPOX_23,J_CHICKENPOX_24,J_CHICKENPOX_26,J_CHICKENPOX_29,J_CHICKENPOX_34,J_CHICKENPOX_43,J_CHICKENPOX_44,J_CHICKENPOX_45,J_CHICKENPOX_46,J_CHICKENPOX_54,J_CHICKENPOX_56,J_CHICKENPOX_64,J_CHICKENPOX_72,J_CHICKENPOX_73,J_CHICKENPOX_74,J_CHICKENPOX_84,J_CHICKENPOX_92,KAM_MX,KAM_STOCKGEN,RCVD_IN_JMF_W,SARE_SPEC_PROLEO_M2,SPF_HELO_PASS,SPF_PASS,ZMIde_GENERICSPAM1 X-Spam-Flag: YES X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (66.187.233.31) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 24 Nov 2008 16:46:51 +0000 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id mAOGkeRM011118 for ; Mon, 24 Nov 2008 11:46:40 -0500 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx1.corp.redhat.com (8.13.1/8.13.1) with ESMTP id mAOGkduE016523 for ; Mon, 24 Nov 2008 11:46:39 -0500 Received: from localhost.localdomain (dhcp231-126.rdu.redhat.com [10.11.231.126]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id mAOGkbav001659; Mon, 24 Nov 2008 11:46:38 -0500 Message-ID: <492ADA6D.7040705@redhat.com> Date: Mon, 24 Nov 2008 16:48:00 -0000 From: William Cohen User-Agent: Thunderbird 2.0.0.18 (X11/20081119) MIME-Version: 1.0 To: Randy Dunlap CC: Peter Teoh , SystemTAP , Don Domingo , "Frank Ch. Eigler" Subject: Re: Start of Systemtap Tapset Reference manual References: <4919B665.2060606@redhat.com> <804dabb00811162156s7cc931deja89861e47571331f@mail.gmail.com> <4922F374.2060609@redhat.com> <492328F5.3080003@oracle.com> <4925D70F.4010602@redhat.com> <4925D92B.50401@oracle.com> In-Reply-To: <4925D92B.50401@oracle.com> Content-Type: multipart/mixed; boundary="------------060802000209010300030008" X-Scanned-By: MIMEDefang 2.58 on 172.16.52.254 X-IsSubscribed: yes Mailing-List: contact systemtap-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Post: List-Help: , Sender: systemtap-owner@sourceware.org X-SW-Source: 2008-q4/txt/msg00410.txt.bz2 This is a multi-part message in MIME format. --------------060802000209010300030008 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Content-length: 784 Randy Dunlap wrote: > Not currently, but I don't see why it couldn't be done. Then the question > becomes: is it the same scripts/kernel-doc file or is it scripts/stap-doc > (e.g. -- or some other name)? This weekend I played around this some more and created some patches to use kernel-doc as method of encoding the documentation in the tapset files. kernel-doc1.patch removes the old documentation method kernel-doc2.patch adds the kernel-doc kernel-doc3.patch revises the tapsets files to generate instumentation. To make the instrumentation need to go in the the build directory doc/SystemTap_Tapset_Reference and do a "make" in there. It dodn't currently install the resulting documtation any where. Comments on this series of patches would be appreciated. -Will --------------060802000209010300030008 Content-Type: text/x-patch; name="kernel-doc1.patch" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="kernel-doc1.patch" Content-length: 150009 >From df812cbc77d205d0f919bbb516f9fc9ddb4deb2a Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 24 Nov 2008 10:19:07 -0500 Subject: [PATCH] Remove the old SystemTap_Tapset_Reference. --- doc/ChangeLog | 4 + doc/SystemTap_Tapset_Reference/Makefile | 19 - .../en-US/Author_Group.xml | 15 - doc/SystemTap_Tapset_Reference/en-US/Book_Info.xml | 33 - doc/SystemTap_Tapset_Reference/en-US/Chapter.xml | 25 - .../en-US/Introduction.xml | 62 - doc/SystemTap_Tapset_Reference/en-US/Preface.xml | 13 - .../en-US/Revision_History.xml | 28 - .../en-US/Tapset_Reference.ent | 5 - .../en-US/Tapset_Reference.xml | 16 - doc/SystemTap_Tapset_Reference/en-US/context.xml | 226 -- .../en-US/images/icon.svg | 3936 -------------------- doc/SystemTap_Tapset_Reference/en-US/memory.xml | 182 - .../en-US/networking.xml | 100 - doc/SystemTap_Tapset_Reference/en-US/timestamp.xml | 50 - doc/SystemTap_Tapset_Reference/extractxml.pl | 137 - 16 files changed, 4 insertions(+), 4847 deletions(-) delete mode 100644 doc/SystemTap_Tapset_Reference/Makefile delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Author_Group.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Book_Info.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Chapter.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Introduction.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Preface.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Revision_History.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.ent delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/context.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/images/icon.svg delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/memory.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/networking.xml delete mode 100644 doc/SystemTap_Tapset_Reference/en-US/timestamp.xml delete mode 100755 doc/SystemTap_Tapset_Reference/extractxml.pl diff --git a/doc/ChangeLog b/doc/ChangeLog index d0b02ad..e59e240 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-11-24 Will Cohen + + * SystemTap_Tapset_Reference: Remove. + 2008-10-23 Will Cohen * SystemTap_Tapset_Reference: New. diff --git a/doc/SystemTap_Tapset_Reference/Makefile b/doc/SystemTap_Tapset_Reference/Makefile deleted file mode 100644 index 5212c16..0000000 --- a/doc/SystemTap_Tapset_Reference/Makefile +++ /dev/null @@ -1,19 +0,0 @@ -#Makefile for SystemTap_Tapset_Reference - -XML_LANG = en-US -BRAND = common - -SHOW_REMARKS=1 - -#OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW - -# Extra Parameters start here - -# Extra Parameters stop here -COMMON_CONFIG = /usr/share/publican -include $(COMMON_CONFIG)/make/Makefile.common - -#Pull the xml out of the tapset -TAPSETS=../../tapset -extract-xml: - ./extractxml.pl $(TAPSETS) ./en-US diff --git a/doc/SystemTap_Tapset_Reference/en-US/Author_Group.xml b/doc/SystemTap_Tapset_Reference/en-US/Author_Group.xml deleted file mode 100644 index 1f39c66..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Author_Group.xml +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - William - Cohen - - Tools - Engineering - - wcohen@redhat.com - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Book_Info.xml b/doc/SystemTap_Tapset_Reference/en-US/Book_Info.xml deleted file mode 100644 index c0fc2eb..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Book_Info.xml +++ /dev/null @@ -1,33 +0,0 @@ - - - - - Tapset Reference - Systemtap - - 0.7.1 - 0 - 0 - - Describes the various instrumentation points and functions - available in SystemTap tapsets. - - - - - - - Logo - - - - &YEAR; - &HOLDER; - - - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Chapter.xml b/doc/SystemTap_Tapset_Reference/en-US/Chapter.xml deleted file mode 100644 index 64b94c9..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Chapter.xml +++ /dev/null @@ -1,25 +0,0 @@ - - - - - Test - - This is a test paragraph - -
- Section 1 Test - - Test of a section - -
- -
- Section 2 Test - - Test of a section - -
- - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Introduction.xml b/doc/SystemTap_Tapset_Reference/en-US/Introduction.xml deleted file mode 100644 index 31e8a78..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Introduction.xml +++ /dev/null @@ -1,62 +0,0 @@ - - - - - Introduction - - SystemTap provides free software (GPL) infrastructure to simplify the - gathering of information about the running Linux system. This assists - diagnosis of a performance or functional problem. SystemTap eliminates the - need for the developer to go through the tedious and disruptive instrument, - recompile, install, and reboot sequence that may be otherwise required to - collect data. - - - - SystemTap provides a simple command line interface and scripting language - for writing instrumentation for a live running kernel. The instrumentation - makes extensive use of the probe points and functions provided in the - tapset library. This document describes the various - probe points and functions. - - -
- Tapset Name Format - -In this guide, tapset definitions appear in the following format: - - -name:return (parameters) - definition - - - - The return field specifies what data type the tapset extracts - and returns from the kernel during a probe (and thus, returns). - Tapsets use 2 data types for return: - long (tapset extracts and returns an integer) and - string (tapset extracts and returns a string). - - - - In some cases, tapsets do not have a return value. This - simply means that the tapset does not extract anything from the kernel. This is common among - asynchronous events such as timers, exit functions, and print functions. - - - - - - -
- - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Preface.xml b/doc/SystemTap_Tapset_Reference/en-US/Preface.xml deleted file mode 100644 index 09c00a1..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Preface.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - - - Preface - - - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Revision_History.xml b/doc/SystemTap_Tapset_Reference/en-US/Revision_History.xml deleted file mode 100644 index 2c92d4b..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Revision_History.xml +++ /dev/null @@ -1,28 +0,0 @@ - - - - - Revision History - - - - 1.0 - October 24, 2008 - - William - Cohen - wcohen@redhat.com - - - - Initial creation of - SystemTap Reference Manual - - - - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.ent b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.ent deleted file mode 100644 index 45fb709..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.ent +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml b/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml deleted file mode 100644 index 404b654..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/Tapset_Reference.xml +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/context.xml b/doc/SystemTap_Tapset_Reference/en-US/context.xml deleted file mode 100644 index 2fa8c63..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/context.xml +++ /dev/null @@ -1,226 +0,0 @@ - - - - - Context Functions - - The context functions provide additional information about the where - the event occurred. - The contact functions can provide information such as a backtrace - where the event occured - and the current register values for the processor. - - - print_regs() - print_regs - - Print a register dump. - - - - print_backtrace() - print_backtrace - - Equivalent to print_stack(backtrace()), - except that deeper stack nesting may be supported. Return nothing. - - - - backtrace:string() - backtrace - - Return a string of hex addresses that are a backtrace of the - stack. It may be truncated due to maximum string length. - - - - execname:string() - execname - - Return the name of the current process. - - - - pid:long () - pid - - Return the id of the current process. - - - - tid:long() - tid - - Return the id of the current thread. - - - - ppid:long() - ppid - - Return the id of the parent process. - - - - pexecname:string() - pexecname - - Return the name of the parent process. - - - - gid:long() - gid - - Return the gid of the current process. - - - - egid:long() - egid - - Return the effective gid of the current process. - - - - uid:long() - uid - - Return the uid of the current process. - - - - euid:long() - euid - - Return the effective uid of the current process. - - - - cpu:long() - cpu - - Return the current cpu number. - - - - print_stack(stk:string) - print_stack - - Perform a symbolic lookup of the addresses in the given string, - which is assumed to be the result of a prior call to - . - Print one line per address, including the address, the - name of the function containing the address, and an estimate of - its position within that function. Return nothing. - - - - pp:string() - pp - - Return the probe point associated with the currently running - probe handler, including alias and wildcard expansion effects. - - - - probefunc:string() - probefunc - - Return the probe point's function name, if known. - - - - probemod:string() - probemod - - Return the probe point's module name, if known. - - - - registers_valid:long() - registers_valid - - Return 1 if register() and u_register() can be used - in the current context, or 0 otherwise. - For example, registers_valid() returns 0 - when called from a begin or end probe. - - - - user_mode:long() - user_mode - - Return 1 if the probe point occurred in user-mode. - - - - is_return:long() - is_return - - Return 1 if the probe point is a return probe. - Deprecated. - - - - target:long() - target - - Return the pid of the target process. - - - - module_name:string() - module_name - - FIXME: need description. - - - - stp_pid:long() - stp_pid - - FIXME: need description. - - - - stack_size:long() - stack_size - - Return the size of the kernel stack. - - - - stack_used:long () - stack_used - - Return how many bytes are currently used in the kernel stack. - - - - stack_unused:long() - stack_unused - - Return how many bytes are currently available in the kernel stack. - - - - caller_addr:long() - caller_addr - - Return the address of the calling function. - Works only for return probes at this time. - - - - - caller:string() - caller - - Return the address and name of the calling function. - Works only for return probes at this time. - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/images/icon.svg b/doc/SystemTap_Tapset_Reference/en-US/images/icon.svg deleted file mode 100644 index c471a60..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/images/icon.svg +++ /dev/null @@ -1,3936 +0,0 @@ - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - id="path2858" /> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/memory.xml b/doc/SystemTap_Tapset_Reference/en-US/memory.xml deleted file mode 100644 index 7bceaa1..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/memory.xml +++ /dev/null @@ -1,182 +0,0 @@ - - - - - Memory Tapset - - This family of probe points is used to probe page fault events. - It contains the following probe points: - - - vm.pagefault - vm.pagefault - - Records that a page fault occurred. - The context is the process which triggered the fault. - - - Arguments: - address - - The address of the faulting memory access. - - - write_access - - Indicates whether this was a write. - - - - - - vm.pagefault.return - vm.pagefault.return - - Records type of fault that occurred. - The context is the process which triggered the fault. - - - - Arguments: - fault_type - The possible values of fault_type are: - Fault values - - - - - - DefineValueReason - - - - VM_FAULT_OOM - 0 - out of memory - - - VM_FAULT_SIGBUS - 1 - if not oom, minor, or major fault, this val - - - VM_FAULT_MINOR - 2 - no blocking operation to handle fault - - - VM_FAULT_MAJOR - 3 - required blocking operation to handle fault - - - -
- - - - - - vm.write_shared - vm.write_shared - - Fires when a process attempts to write to a shared page. - If a copy is necessary, this will be followed by a - . - The context is the process attempting the write. - - - - Arguments: - address - The address of the shared write. - - - - - vm.write_shared_copy - vm.write_shared_copy - - Fires when a write to a shared page requires a page copy. - This is always preceded by a . - The context is the process attempting the write. - - - - Arguments: - address - - The address of the shared write. - - - zero - - Boolean indicating whether it is a zero page - (can do a clear instead of a copy). - - - - - - vm.mmap - vm.mmap - - Fires when an mmap is requested. - The context is the process calling mmap. - - - - Arguments: - address - The requested address. - - length - The length of the memory segment. - - - - - vm.munmap - vm.munmap - Fires when an munmap is requested. - - - Arguments: - address - The requested address. - - length - The length of the memory segment. - - - - - vm.brk - vm.brk - Fires when a brk is requested (resizing a heap). - - - Arguments: - address - The requested address. - - length - The length of the memory segment. - - - - - vm.oom_kill - vm.oom_kill - Fires when a thread is targetted by the OOM killer. - - - Arguments: - task - The task being killed. - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/networking.xml b/doc/SystemTap_Tapset_Reference/en-US/networking.xml deleted file mode 100644 index bb5cfea..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/networking.xml +++ /dev/null @@ -1,100 +0,0 @@ - - - - - Networking Tapset - - This family of probe points is used to probe the activities of - network device. - - - netdev.receive - netdev.receive - Fires when data arrives on network device. - - - Arguments: - dev_name - - The name of the device. e.g: eth0, ath1 - - - - length - - The length of the receiving buffer - - - - protocol - The possible values of protocol could be: - Protocol Values - - - - - Value(Hex)Protocol - - - 0001802.3 - 0002AX.25 - 0004802.2 - 0005SNAP - 0009Localtalk - 0800IP - 0805X.25 - 0806ARP - 8035RARP - 8100802.1Q VLAN - 8137IPX - 86DDIPv6 - - -
- - - - truesize - - The size of the received data. - - - - - - - netdev.transmit - netdev.transmit - Fires when the network device wants to transmit a buffer. - - - Arguments: - dev_name - - The name of the device. e.g: eth0, ath1 - - - - length - - The length of the transmit buffer - - - - protocol - - The protocol of this packet. - - - - truesize - - The size of the the data to be transmitted. - - - - - - diff --git a/doc/SystemTap_Tapset_Reference/en-US/timestamp.xml b/doc/SystemTap_Tapset_Reference/en-US/timestamp.xml deleted file mode 100644 index 714f16b..0000000 --- a/doc/SystemTap_Tapset_Reference/en-US/timestamp.xml +++ /dev/null @@ -1,50 +0,0 @@ - - - - - Timestamp Functions - - Each timestamp function returns a value to indicate when - the function is executed. - Thus, these returned values can be used to indicate - when an event occurs, provide an ordering for events, or compute - the amount of time elapsed between to time stamps. - - - get_cycles:long() - get_cycles - - Return the processor cycle counter value, or 0 if unavailable. - - - - gettimeofday_ns:long () - gettimeofday_ns - - Return the number of nanoseconds since the UNIX epoch. - - - - gettimeofday_us:long () - gettimeofday_us - - Return the number of microseconds since the UNIX epoch. - - - - gettimeofday_ms:long () - gettimeofday_ms - - Return the number of milliseconds since the UNIX epoch. - - - - gettimeofday_s:long () - gettimeofday_s - - Return the number of seconds since the UNIX epoch. - - - diff --git a/doc/SystemTap_Tapset_Reference/extractxml.pl b/doc/SystemTap_Tapset_Reference/extractxml.pl deleted file mode 100755 index 492a29c..0000000 --- a/doc/SystemTap_Tapset_Reference/extractxml.pl +++ /dev/null @@ -1,137 +0,0 @@ -#! /usr/bin/perl -# Generates xml files from tapset .stp files. -# Copyright (C) 2008 Red Hat Inc. -# -# This file is part of systemtap, and is free software. You can -# redistribute it and/or modify it under the terms of the GNU General -# Public License (GPL); either version 2, or (at your option) any -# later version. - -use strict; -use warnings; - -use Cwd 'abs_path'; -use File::Copy; -use File::Find; -use File::Path; -use Text::Wrap; -use IO::File; -use POSIX qw(tmpnam); - -my $XMLHEADER = - "\n" - . "\n" - ."\n" - . "\n" - . "\n" - . "\n" - . "\n" -; -my $XMLFOOTER = - "\n" - . "\n" - ."\n"; - -my $XML_CHAPTER_HEADER = - "\n" - . "\n" - . "\n"; - -my $XML_CHAPTER_FOOTER = ""; - -my $inputdir; -if ($#ARGV >= 0) { - $inputdir = $ARGV[0]; -} else { - $inputdir = "."; -} -$inputdir = abs_path($inputdir); - -my $outputdir; -if ($#ARGV >= 1) { - $outputdir = $ARGV[1]; -} else { - $outputdir = $inputdir; -} -$outputdir = abs_path($outputdir); - -#attempt to create the output directory -if ($inputdir ne $outputdir) { - if (! -d "$outputdir") { - mkpath("$outputdir", 1, 0711); - } -} - -my %scripts = (); - -print "Extracting xml from .stp files in $inputdir...\n"; -find(\&extract_xml, $inputdir); - - -# Output list of extracted xml files -my $tapsetxml = "$outputdir/Tapset_Reference.xml"; -open (TAPSETXML, ">$tapsetxml") - || die "couldn't open $tapsetxml: $!"; -print "Creating $tapsetxml...\n"; -print TAPSETXML $XMLHEADER; - -my $tapset; -foreach $tapset (sort keys %scripts) { - print TAPSETXML "\n" - -} -print TAPSETXML $XMLFOOTER; -close (TAPSETXML); - - -sub extract_xml { - my $file = $_; - my $filename = $File::Find::name; - my $ofile; - my $ofilefullt; - my $ofilefull; - - if (-f $file && $file =~ /\.stp$/) { - open FILE, $file or die "couldn't open '$file': $!\n"; - - $ofilefullt = tmpnam(); - open OFILET, ">$ofilefullt" or die "couldn't open '$ofilefullt': $!\n"; - - print "Extracting xml from $filename...\n"; - - while () { - print OFILET if s/\s*\/\/\///; - } - close OFILET; - close FILE; - - #If xml was extracted make a .xml file - if (-s $ofilefullt) { - #get rid of the inputdir part and .stp, add .xml - # chop off the search dir prefix. - $inputdir =~ s/\/$//; - $ofile = substr $filename, (length $inputdir) + 1; - $ofile =~ s/.stp/.xml/; - $ofile =~ s/\//_/g; - $scripts{$ofile} = $ofile; - print "$ofile\n"; - $ofilefull = "$outputdir/$ofile"; - open OFILE, ">$ofilefull" - or die "couldn't open '$ofilefull': $!\n"; - open OFILET, "$ofilefullt" - or die "couldn't open '$ofilefullt': $!\n"; - print OFILE "$XML_CHAPTER_HEADER"; - while () { - print OFILE ; - } - print OFILE "$XML_CHAPTER_FOOTER"; - close OFILET; - close OFILE; - } - unlink($ofilefullt); - } -} -- 1.5.6.5 --------------060802000209010300030008 Content-Type: text/x-patch; name="kernel-doc2.patch" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="kernel-doc2.patch" Content-length: 103986 >From 45451e50f27e29fece12a3ee9747514806a65795 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 24 Nov 2008 10:34:29 -0500 Subject: [PATCH] Add kernel-doc based version of SystemTap_Tapset_Reference. --- ChangeLog | 6 + configure | 3 +- configure.ac | 2 +- doc/ChangeLog | 4 + doc/SystemTap_Tapset_Reference/Makefile.am | 37 + doc/SystemTap_Tapset_Reference/Makefile.in | 458 ++++++ doc/SystemTap_Tapset_Reference/docproc.c | 448 +++++ doc/SystemTap_Tapset_Reference/tapsets.tmpl | 115 ++ scripts/kernel-doc | 2356 +++++++++++++++++++++++++++ 9 files changed, 3427 insertions(+), 2 deletions(-) create mode 100644 doc/SystemTap_Tapset_Reference/Makefile.am create mode 100644 doc/SystemTap_Tapset_Reference/Makefile.in create mode 100644 doc/SystemTap_Tapset_Reference/docproc.c create mode 100644 doc/SystemTap_Tapset_Reference/tapsets.tmpl create mode 100755 scripts/kernel-doc diff --git a/ChangeLog b/ChangeLog index cd0cd73..4742a41 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-11-24 Will Cohen + + * scripts/kernel-doc: New. + * configure.ac: Add doc/SystemTap_Tapset_Reference/Makefile. + * configure, doc/SystemTap_Tapset_Reference/Makefile.in: Regenerate. + 2008-11-22 Frank Ch. Eigler * tapsets.cxx (MAXUPROBES): Tweak its definition. Use it diff --git a/configure b/configure index c5bccb2..dc40c1e 100755 --- a/configure +++ b/configure @@ -6995,7 +6995,7 @@ ac_compiler_gnu=$ac_cv_c_compiler_gnu ac_config_headers="$ac_config_headers config.h:config.in" -ac_config_files="$ac_config_files Makefile doc/Makefile stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5" +ac_config_files="$ac_config_files Makefile doc/Makefile doc/SystemTap_Tapset_Reference/Makefile stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5" subdirs="$subdirs testsuite" @@ -7623,6 +7623,7 @@ do "config.h") CONFIG_HEADERS="$CONFIG_HEADERS config.h:config.in" ;; "Makefile") CONFIG_FILES="$CONFIG_FILES Makefile" ;; "doc/Makefile") CONFIG_FILES="$CONFIG_FILES doc/Makefile" ;; + "doc/SystemTap_Tapset_Reference/Makefile") CONFIG_FILES="$CONFIG_FILES doc/SystemTap_Tapset_Reference/Makefile" ;; "stap.1") CONFIG_FILES="$CONFIG_FILES stap.1" ;; "stapprobes.5") CONFIG_FILES="$CONFIG_FILES stapprobes.5" ;; "stapfuncs.5") CONFIG_FILES="$CONFIG_FILES stapfuncs.5" ;; diff --git a/configure.ac b/configure.ac index aec2a55..108a519 100644 --- a/configure.ac +++ b/configure.ac @@ -221,7 +221,7 @@ AC_CHECK_HEADERS([tr1/unordered_map]) AC_LANG_POP(C++) AC_CONFIG_HEADERS([config.h:config.in]) -AC_CONFIG_FILES(Makefile doc/Makefile stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5) +AC_CONFIG_FILES(Makefile doc/Makefile doc/SystemTap_Tapset_Reference/Makefile stap.1 stapprobes.5 stapfuncs.5 stapvars.5 stapex.5 staprun.8 stap-server.8 man/stapprobes.iosched.5 man/stapprobes.netdev.5 man/stapprobes.nfs.5 man/stapprobes.nfsd.5 man/stapprobes.pagefault.5 man/stapprobes.process.5 man/stapprobes.rpc.5 man/stapprobes.scsi.5 man/stapprobes.signal.5 man/stapprobes.socket.5 man/stapprobes.tcp.5 man/stapprobes.udp.5) AC_CONFIG_SUBDIRS(testsuite) AC_OUTPUT diff --git a/doc/ChangeLog b/doc/ChangeLog index e59e240..ac2d01a 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,9 @@ 2008-11-24 Will Cohen + * SystemTap_Tapset_Reference: Add kernel-doc based version. + +2008-11-24 Will Cohen + * SystemTap_Tapset_Reference: Remove. 2008-10-23 Will Cohen diff --git a/doc/SystemTap_Tapset_Reference/Makefile.am b/doc/SystemTap_Tapset_Reference/Makefile.am new file mode 100644 index 0000000..8327e90 --- /dev/null +++ b/doc/SystemTap_Tapset_Reference/Makefile.am @@ -0,0 +1,37 @@ +# Makefile.am --- automake input file for systemtap tapset reference manual +## process this file with automake to produce Makefile.in + +### +# The build process is as follows (targets): +# (xmldocs) [by docproc] +# file.tmpl --> file.xml +--> file.ps (psdocs) [by xmlto] +# +--> file.pdf (pdfdocs) [by xmlto] +# +--> DIR=file (htmldocs) [by xmlto] +# +--> man/ (mandocs) [by xmlto] + +bin_PROGRAMS = docproc +docproc_SOURCES = docproc.c + +all: pdfdocs htmldocs mandocs + + +SRCTREE=$(abs_top_srcdir)/ +DOCPROC=$(abs_builddir)/docproc + +xmldocs: docproc + SRCTREE=$(SRCTREE) $(DOCPROC) doc $(abs_srcdir)/tapsets.tmpl > tapsets.xml + +htmldocs: xmldocs + xmlto html -o tapset tapsets.xml + +pdfdocs: xmldocs + xmlto pdf tapsets.xml + +mandocs: xmldocs + xmlto man tapsets.xml + +#FIXME need to figure out where to install things appropriately +#installmandocs: mandocs +# $(MKDIR_P) /usr/local/man/man5/ +# install Documentation/DocBook/man/*.5.gz /usr/local/man/man5/ + diff --git a/doc/SystemTap_Tapset_Reference/Makefile.in b/doc/SystemTap_Tapset_Reference/Makefile.in new file mode 100644 index 0000000..5dff66f --- /dev/null +++ b/doc/SystemTap_Tapset_Reference/Makefile.in @@ -0,0 +1,458 @@ +# Makefile.in generated by automake 1.10.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Makefile.am --- automake input file for systemtap tapset reference manual + +### +# The build process is as follows (targets): +# (xmldocs) [by docproc] +# file.tmpl --> file.xml +--> file.ps (psdocs) [by xmlto] +# +--> file.pdf (pdfdocs) [by xmlto] +# +--> DIR=file (htmldocs) [by xmlto] +# +--> man/ (mandocs) [by xmlto] + +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +bin_PROGRAMS = docproc$(EXEEXT) +subdir = doc/SystemTap_Tapset_Reference +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +am__installdirs = "$(DESTDIR)$(bindir)" +binPROGRAMS_INSTALL = $(INSTALL_PROGRAM) +PROGRAMS = $(bin_PROGRAMS) +am_docproc_OBJECTS = docproc.$(OBJEXT) +docproc_OBJECTS = $(am_docproc_OBJECTS) +docproc_LDADD = $(LDADD) +DEFAULT_INCLUDES = -I.@am__isrc@ -I$(top_builddir) +depcomp = $(SHELL) $(top_srcdir)/depcomp +am__depfiles_maybe = depfiles +COMPILE = $(CC) $(DEFS) $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \ + $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +CCLD = $(CC) +LINK = $(CCLD) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) -o $@ +SOURCES = $(docproc_SOURCES) +DIST_SOURCES = $(docproc_SOURCES) +ETAGS = etags +CTAGS = ctags +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DATE = @DATE@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAINT = @MAINT@ +MAKEINFO = @MAKEINFO@ +MKDIR_P = @MKDIR_P@ +OBJEXT = @OBJEXT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PIELDFLAGS = @PIELDFLAGS@ +PROCFLAGS = @PROCFLAGS@ +RANLIB = @RANLIB@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +U = @U@ +VERSION = @VERSION@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build_alias = @build_alias@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +elfutils_abs_srcdir = @elfutils_abs_srcdir@ +exec_prefix = @exec_prefix@ +have_dvips = @have_dvips@ +have_latex = @have_latex@ +have_latex2html = @have_latex2html@ +have_ps2pdf = @have_ps2pdf@ +host_alias = @host_alias@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +sqlite3_LIBS = @sqlite3_LIBS@ +srcdir = @srcdir@ +stap_LIBS = @stap_LIBS@ +staplog_CPPFLAGS = @staplog_CPPFLAGS@ +subdirs = @subdirs@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +docproc_SOURCES = docproc.c +SRCTREE = $(abs_top_srcdir)/ +DOCPROC = $(abs_builddir)/docproc +all: all-am + +.SUFFIXES: +.SUFFIXES: .c .o .obj +$(srcdir)/Makefile.in: @MAINTAINER_MODE_TRUE@ $(srcdir)/Makefile.am $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/SystemTap_Tapset_Reference/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/SystemTap_Tapset_Reference/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: @MAINTAINER_MODE_TRUE@ $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): @MAINTAINER_MODE_TRUE@ $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +install-binPROGRAMS: $(bin_PROGRAMS) + @$(NORMAL_INSTALL) + test -z "$(bindir)" || $(MKDIR_P) "$(DESTDIR)$(bindir)" + @list='$(bin_PROGRAMS)'; for p in $$list; do \ + p1=`echo $$p|sed 's/$(EXEEXT)$$//'`; \ + if test -f $$p \ + ; then \ + f=`echo "$$p1" | sed 's,^.*/,,;$(transform);s/$$/$(EXEEXT)/'`; \ + echo " $(INSTALL_PROGRAM_ENV) $(binPROGRAMS_INSTALL) '$$p' '$(DESTDIR)$(bindir)/$$f'"; \ + $(INSTALL_PROGRAM_ENV) $(binPROGRAMS_INSTALL) "$$p" "$(DESTDIR)$(bindir)/$$f" || exit 1; \ + else :; fi; \ + done + +uninstall-binPROGRAMS: + @$(NORMAL_UNINSTALL) + @list='$(bin_PROGRAMS)'; for p in $$list; do \ + f=`echo "$$p" | sed 's,^.*/,,;s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/'`; \ + echo " rm -f '$(DESTDIR)$(bindir)/$$f'"; \ + rm -f "$(DESTDIR)$(bindir)/$$f"; \ + done + +clean-binPROGRAMS: + -test -z "$(bin_PROGRAMS)" || rm -f $(bin_PROGRAMS) +docproc$(EXEEXT): $(docproc_OBJECTS) $(docproc_DEPENDENCIES) + @rm -f docproc$(EXEEXT) + $(LINK) $(docproc_OBJECTS) $(docproc_LDADD) $(LIBS) + +mostlyclean-compile: + -rm -f *.$(OBJEXT) + +distclean-compile: + -rm -f *.tab.c + +@AMDEP_TRUE@@am__include@ @am__quote@./$(DEPDIR)/docproc.Po@am__quote@ + +.c.o: +@am__fastdepCC_TRUE@ $(COMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ $< +@am__fastdepCC_TRUE@ mv -f $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Po +@AMDEP_TRUE@@am__fastdepCC_FALSE@ source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ +@AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ +@am__fastdepCC_FALSE@ $(COMPILE) -c $< + +.c.obj: +@am__fastdepCC_TRUE@ $(COMPILE) -MT $@ -MD -MP -MF $(DEPDIR)/$*.Tpo -c -o $@ `$(CYGPATH_W) '$<'` +@am__fastdepCC_TRUE@ mv -f $(DEPDIR)/$*.Tpo $(DEPDIR)/$*.Po +@AMDEP_TRUE@@am__fastdepCC_FALSE@ source='$<' object='$@' libtool=no @AMDEPBACKSLASH@ +@AMDEP_TRUE@@am__fastdepCC_FALSE@ DEPDIR=$(DEPDIR) $(CCDEPMODE) $(depcomp) @AMDEPBACKSLASH@ +@am__fastdepCC_FALSE@ $(COMPILE) -c `$(CYGPATH_W) '$<'` + +ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonemtpy = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + mkid -fID $$unique +tags: TAGS + +TAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + tags=; \ + here=`pwd`; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \ + test -n "$$unique" || unique=$$empty_fix; \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$tags $$unique; \ + fi +ctags: CTAGS +CTAGS: $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + tags=; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + test -z "$(CTAGS_ARGS)$$tags$$unique" \ + || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ + $$tags $$unique + +GTAGS: + here=`$(am__cd) $(top_builddir) && pwd` \ + && cd $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) $$here + +distclean-tags: + -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile $(PROGRAMS) +installdirs: + for dir in "$(DESTDIR)$(bindir)"; do \ + test -z "$$dir" || $(MKDIR_P) "$$dir"; \ + done +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-binPROGRAMS clean-generic mostlyclean-am + +distclean: distclean-am + -rm -rf ./$(DEPDIR) + -rm -f Makefile +distclean-am: clean-am distclean-compile distclean-generic \ + distclean-tags + +dvi: dvi-am + +dvi-am: + +html: html-am + +info: info-am + +info-am: + +install-data-am: + +install-dvi: install-dvi-am + +install-exec-am: install-binPROGRAMS + +install-html: install-html-am + +install-info: install-info-am + +install-man: + +install-pdf: install-pdf-am + +install-ps: install-ps-am + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -rf ./$(DEPDIR) + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-compile mostlyclean-generic + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: uninstall-binPROGRAMS + +.MAKE: install-am install-strip + +.PHONY: CTAGS GTAGS all all-am check check-am clean clean-binPROGRAMS \ + clean-generic ctags distclean distclean-compile \ + distclean-generic distclean-tags distdir dvi dvi-am html \ + html-am info info-am install install-am install-binPROGRAMS \ + install-data install-data-am install-dvi install-dvi-am \ + install-exec install-exec-am install-html install-html-am \ + install-info install-info-am install-man install-pdf \ + install-pdf-am install-ps install-ps-am install-strip \ + installcheck installcheck-am installdirs maintainer-clean \ + maintainer-clean-generic mostlyclean mostlyclean-compile \ + mostlyclean-generic pdf pdf-am ps ps-am tags uninstall \ + uninstall-am uninstall-binPROGRAMS + + +all: pdfdocs htmldocs mandocs + +xmldocs: docproc + SRCTREE=$(SRCTREE) $(DOCPROC) doc $(abs_srcdir)/tapsets.tmpl > tapsets.xml + +htmldocs: xmldocs + xmlto html -o tapset tapsets.xml + +pdfdocs: xmldocs + xmlto pdf tapsets.xml + +mandocs: xmldocs + xmlto man tapsets.xml + +#FIXME need to figure out where to install things appropriately +#installmandocs: mandocs +# $(MKDIR_P) /usr/local/man/man5/ +# install Documentation/DocBook/man/*.5.gz /usr/local/man/man5/ +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/doc/SystemTap_Tapset_Reference/docproc.c b/doc/SystemTap_Tapset_Reference/docproc.c new file mode 100644 index 0000000..35bdc68 --- /dev/null +++ b/doc/SystemTap_Tapset_Reference/docproc.c @@ -0,0 +1,448 @@ +/* + * docproc is a simple preprocessor for the template files + * used as placeholders for the kernel internal documentation. + * docproc is used for documentation-frontend and + * dependency-generator. + * The two usages have in common that they require + * some knowledge of the .tmpl syntax, therefore they + * are kept together. + * + * documentation-frontend + * Scans the template file and call kernel-doc for + * all occurrences of ![EIF]file + * Beforehand each referenced file is scanned for + * any symbols that are exported via these macros: + * EXPORT_SYMBOL(), EXPORT_SYMBOL_GPL(), & + * EXPORT_SYMBOL_GPL_FUTURE() + * This is used to create proper -function and + * -nofunction arguments in calls to kernel-doc. + * Usage: docproc doc file.tmpl + * + * dependency-generator: + * Scans the template file and list all files + * referenced in a format recognized by make. + * Usage: docproc depend file.tmpl + * Writes dependency information to stdout + * in the following format: + * file.tmpl src.c src2.c + * The filenames are obtained from the following constructs: + * !Efilename + * !Ifilename + * !Dfilename + * !Ffilename + * !Pfilename + * + */ + +#include +#include +#include +#include +#include +#include +#include +#include + +/* exitstatus is used to keep track of any failing calls to kernel-doc, + * but execution continues. */ +int exitstatus = 0; + +typedef void DFL(char *); +DFL *defaultline; + +typedef void FILEONLY(char * file); +FILEONLY *internalfunctions; +FILEONLY *externalfunctions; +FILEONLY *symbolsonly; + +typedef void FILELINE(char * file, char * line); +FILELINE * singlefunctions; +FILELINE * entity_system; +FILELINE * docsection; + +#define MAXLINESZ 2048 +#define MAXFILES 250 +#define KERNELDOCPATH "scripts/" +#define KERNELDOC "kernel-doc" +#define DOCBOOK "-docbook" +#define FUNCTION "-function" +#define NOFUNCTION "-nofunction" +#define NODOCSECTIONS "-no-doc-sections" + +char *srctree; + +void usage (void) +{ + fprintf(stderr, "Usage: docproc {doc|depend} file\n"); + fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n"); + fprintf(stderr, "doc: frontend when generating kernel documentation\n"); + fprintf(stderr, "depend: generate list of files referenced within file\n"); + fprintf(stderr, "Environment variable SRCTREE: absolute path to kernel source tree.\n"); +} + +/* + * Execute kernel-doc with parameters given in svec + */ +void exec_kernel_doc(char **svec) +{ + pid_t pid; + int ret; + char real_filename[PATH_MAX + 1]; + /* Make sure output generated so far are flushed */ + fflush(stdout); + switch (pid=fork()) { + case -1: + perror("fork"); + exit(1); + case 0: + memset(real_filename, 0, sizeof(real_filename)); + strncat(real_filename, srctree, PATH_MAX); + strncat(real_filename, KERNELDOCPATH KERNELDOC, + PATH_MAX - strlen(real_filename)); + execvp(real_filename, svec); + fprintf(stderr, "exec "); + perror(real_filename); + exit(1); + default: + waitpid(pid, &ret ,0); + } + if (WIFEXITED(ret)) + exitstatus |= WEXITSTATUS(ret); + else + exitstatus = 0xff; +} + +/* Types used to create list of all exported symbols in a number of files */ +struct symbols +{ + char *name; +}; + +struct symfile +{ + char *filename; + struct symbols *symbollist; + int symbolcnt; +}; + +struct symfile symfilelist[MAXFILES]; +int symfilecnt = 0; + +void add_new_symbol(struct symfile *sym, char * symname) +{ + sym->symbollist = + realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); + sym->symbollist[sym->symbolcnt++].name = strdup(symname); +} + +/* Add a filename to the list */ +struct symfile * add_new_file(char * filename) +{ + symfilelist[symfilecnt++].filename = strdup(filename); + return &symfilelist[symfilecnt - 1]; +} + +/* Check if file already are present in the list */ +struct symfile * filename_exist(char * filename) +{ + int i; + for (i=0; i < symfilecnt; i++) + if (strcmp(symfilelist[i].filename, filename) == 0) + return &symfilelist[i]; + return NULL; +} + +/* + * List all files referenced within the template file. + * Files are separated by tabs. + */ +void adddep(char * file) { printf("\t%s", file); } +void adddep2(char * file, char * line) { line = line; adddep(file); } +void noaction(char * line) { line = line; } +void noaction2(char * file, char * line) { file = file; line = line; } + +/* Echo the line without further action */ +void printline(char * line) { printf("%s", line); } + +/* + * Find all symbols in filename that are exported with EXPORT_SYMBOL & + * EXPORT_SYMBOL_GPL (& EXPORT_SYMBOL_GPL_FUTURE implicitly). + * All symbols located are stored in symfilelist. + */ +void find_export_symbols(char * filename) +{ + FILE * fp; + struct symfile *sym; + char line[MAXLINESZ]; + if (filename_exist(filename) == NULL) { + char real_filename[PATH_MAX + 1]; + memset(real_filename, 0, sizeof(real_filename)); + strncat(real_filename, srctree, PATH_MAX); + strncat(real_filename, filename, + PATH_MAX - strlen(real_filename)); + sym = add_new_file(filename); + fp = fopen(real_filename, "r"); + if (fp == NULL) + { + fprintf(stderr, "docproc: "); + perror(real_filename); + exit(1); + } + while (fgets(line, MAXLINESZ, fp)) { + char *p; + char *e; + if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) || + ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { + /* Skip EXPORT_SYMBOL{_GPL} */ + while (isalnum(*p) || *p == '_') + p++; + /* Remove parentheses & additional whitespace */ + while (isspace(*p)) + p++; + if (*p != '(') + continue; /* Syntax error? */ + else + p++; + while (isspace(*p)) + p++; + e = p; + while (isalnum(*e) || *e == '_') + e++; + *e = '\0'; + add_new_symbol(sym, p); + } + } + fclose(fp); + } +} + +/* + * Document all external or internal functions in a file. + * Call kernel-doc with following parameters: + * kernel-doc -docbook -nofunction function_name1 filename + * Function names are obtained from all the src files + * by find_export_symbols. + * intfunc uses -nofunction + * extfunc uses -function + */ +void docfunctions(char * filename, char * type) +{ + int i,j; + int symcnt = 0; + int idx = 0; + char **vec; + + for (i=0; i <= symfilecnt; i++) + symcnt += symfilelist[i].symbolcnt; + vec = malloc((2 + 2 * symcnt + 3) * sizeof(char *)); + if (vec == NULL) { + perror("docproc: "); + exit(1); + } + vec[idx++] = KERNELDOC; + vec[idx++] = DOCBOOK; + vec[idx++] = NODOCSECTIONS; + for (i=0; i < symfilecnt; i++) { + struct symfile * sym = &symfilelist[i]; + for (j=0; j < sym->symbolcnt; j++) { + vec[idx++] = type; + vec[idx++] = sym->symbollist[j].name; + } + } + vec[idx++] = filename; + vec[idx] = NULL; + printf("\n", filename); + exec_kernel_doc(vec); + fflush(stdout); + free(vec); +} +void intfunc(char * filename) { docfunctions(filename, NOFUNCTION); } +void extfunc(char * filename) { docfunctions(filename, FUNCTION); } + +/* + * Document specific function(s) in a file. + * Call kernel-doc with the following parameters: + * kernel-doc -docbook -function function1 [-function function2] + */ +void singfunc(char * filename, char * line) +{ + char *vec[200]; /* Enough for specific functions */ + int i, idx = 0; + int startofsym = 1; + vec[idx++] = KERNELDOC; + vec[idx++] = DOCBOOK; + + /* Split line up in individual parameters preceded by FUNCTION */ + for (i=0; line[i]; i++) { + if (isspace(line[i])) { + line[i] = '\0'; + startofsym = 1; + continue; + } + if (startofsym) { + startofsym = 0; + vec[idx++] = FUNCTION; + vec[idx++] = &line[i]; + } + } + vec[idx++] = filename; + vec[idx] = NULL; + exec_kernel_doc(vec); +} + +/* + * Insert specific documentation section from a file. + * Call kernel-doc with the following parameters: + * kernel-doc -docbook -function "doc section" filename + */ +void docsect(char *filename, char *line) +{ + char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */ + char *s; + + for (s = line; *s; s++) + if (*s == '\n') + *s = '\0'; + + vec[0] = KERNELDOC; + vec[1] = DOCBOOK; + vec[2] = FUNCTION; + vec[3] = line; + vec[4] = filename; + vec[5] = NULL; + exec_kernel_doc(vec); +} + +/* + * Parse file, calling action specific functions for: + * 1) Lines containing !E + * 2) Lines containing !I + * 3) Lines containing !D + * 4) Lines containing !F + * 5) Lines containing !P + * 6) Default lines - lines not matching the above + */ +void parse_file(FILE *infile) +{ + char line[MAXLINESZ]; + char * s; + while (fgets(line, MAXLINESZ, infile)) { + if (line[0] == '!') { + s = line + 2; + switch (line[1]) { + case 'E': + while (*s && !isspace(*s)) s++; + *s = '\0'; + externalfunctions(line+2); + break; + case 'I': + while (*s && !isspace(*s)) s++; + *s = '\0'; + internalfunctions(line+2); + break; + case 'D': + while (*s && !isspace(*s)) s++; + *s = '\0'; + symbolsonly(line+2); + break; + case 'F': + /* filename */ + while (*s && !isspace(*s)) s++; + *s++ = '\0'; + /* function names */ + while (isspace(*s)) + s++; + singlefunctions(line +2, s); + break; + case 'P': + /* filename */ + while (*s && !isspace(*s)) s++; + *s++ = '\0'; + /* DOC: section name */ + while (isspace(*s)) + s++; + docsection(line + 2, s); + break; + default: + defaultline(line); + } + } + else { + defaultline(line); + } + } + fflush(stdout); +} + + +int main(int argc, char *argv[]) +{ + FILE * infile; + + srctree = getenv("SRCTREE"); + if (!srctree) + srctree = getcwd(NULL, 0); + if (argc != 3) { + usage(); + exit(1); + } + /* Open file, exit on error */ + infile = fopen(argv[2], "r"); + if (infile == NULL) { + fprintf(stderr, "docproc: "); + perror(argv[2]); + exit(2); + } + + if (strcmp("doc", argv[1]) == 0) + { + /* Need to do this in two passes. + * First pass is used to collect all symbols exported + * in the various files; + * Second pass generate the documentation. + * This is required because some functions are declared + * and exported in different files :-(( + */ + /* Collect symbols */ + defaultline = noaction; + internalfunctions = find_export_symbols; + externalfunctions = find_export_symbols; + symbolsonly = find_export_symbols; + singlefunctions = noaction2; + docsection = noaction2; + parse_file(infile); + + /* Rewind to start from beginning of file again */ + fseek(infile, 0, SEEK_SET); + defaultline = printline; + internalfunctions = intfunc; + externalfunctions = extfunc; + symbolsonly = printline; + singlefunctions = singfunc; + docsection = docsect; + + parse_file(infile); + } + else if (strcmp("depend", argv[1]) == 0) + { + /* Create first part of dependency chain + * file.tmpl */ + printf("%s\t", argv[2]); + defaultline = noaction; + internalfunctions = adddep; + externalfunctions = adddep; + symbolsonly = adddep; + singlefunctions = adddep2; + docsection = adddep2; + parse_file(infile); + printf("\n"); + } + else + { + fprintf(stderr, "Unknown option: %s\n", argv[1]); + exit(1); + } + fclose(infile); + fflush(stdout); + return exitstatus; +} diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl new file mode 100644 index 0000000..8ae22ed --- /dev/null +++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl @@ -0,0 +1,115 @@ + + + + + + SystemTap Tapset Reference Manual + + + + Willliam + Cohen + +
+ wcohen@redhat.com +
+ + + + + + 2008 + Red Hat, Inc. + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + SystemTap provides free software (GPL) infrastructure to simplify the + gathering of information about the running Linux system. This assists + diagnosis of a performance or functional problem. SystemTap eliminates the + need for the developer to go through the tedious and disruptive instrument, + recompile, install, and reboot sequence that may be otherwise required to + collect data. + + + + SystemTap provides a simple command line interface and scripting language + for writing instrumentation for a live running kernel. The instrumentation + makes extensive use of the probe points and functions provided in the + tapset library. This document describes the various + probe points and functions. + + +
+ Tapset Name Format + + In this guide, tapset definitions appear in the following format: + + + name:return (parameters) + definition + + + + The return field specifies what data type the + tapset extracts and returns from the kernel during a probe (and thus, + returns). Tapsets use 2 data types for + return: long (tapset + extracts and returns an integer) and string (tapset + extracts and returns a string). + + + + In some cases, tapsets do not have a return v +alue. This + simply means that the tapset does not extract anything from the kernel. +This is common among + asynchronous events such as timers, exit functions, and print functions. + + + + +
+ + + + diff --git a/scripts/kernel-doc b/scripts/kernel-doc new file mode 100755 index 0000000..1ed3432 --- /dev/null +++ b/scripts/kernel-doc @@ -0,0 +1,2356 @@ +#!/usr/bin/perl -w + +use strict; + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## Copyright (C) 2000, 1 Tim Waugh ## +## Copyright (C) 2001 Simon Huggins ## +## Copyright (C) 2005-2008 Randy Dunlap ## +## ## +## #define enhancements by Armin Kuster ## +## Copyright (c) 2000 MontaVista Software, Inc. ## +## ## +## This software falls under the GNU General Public License. ## +## Please read the COPYING file for more information ## + +# w.o. 03-11-2000: added the '-filelist' option. + +# 18/01/2001 - Cleanups +# Functions prototyped as foo(void) same as foo() +# Stop eval'ing where we don't need to. +# -- huggie@earth.li + +# 27/06/2001 - Allowed whitespace after initial "/**" and +# allowed comments before function declarations. +# -- Christian Kreibich + +# Still to do: +# - add perldoc documentation +# - Look more closely at some of the scarier bits :) + +# 26/05/2001 - Support for separate source and object trees. +# Return error code. +# Keith Owens + +# 23/09/2001 - Added support for typedefs, structs, enums and unions +# Support for Context section; can be terminated using empty line +# Small fixes (like spaces vs. \s in regex) +# -- Tim Jansen + + +# +# This will read a 'c' file and scan for embedded comments in the +# style of gnome comments (+minor extensions - see below). +# + +# Note: This only supports 'c'. + +# usage: +# kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ] +# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile +# or +# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile +# +# Set output format using one of -docbook -html -text or -man. Default is man. +# +# -no-doc-sections +# Do not output DOC: sections +# +# -function funcname +# If set, then only generate documentation for the given function(s) or +# DOC: section titles. All other functions and DOC: sections are ignored. +# +# -nofunction funcname +# If set, then only generate documentation for the other function(s)/DOC: +# sections. Cannot be used together with -function (yes, that's a bug -- +# perl hackers can fix it 8)) +# +# c files - list of 'c' files to process +# +# All output goes to stdout, with errors to stderr. + +# +# format of comments. +# In the following table, (...)? signifies optional structure. +# (...)* signifies 0 or more structure elements +# /** +# * function_name(:)? (- short description)? +# (* @parameterx: (description of parameter x)?)* +# (* a blank line)? +# * (Description:)? (Description of function)? +# * (section header: (section description)? )* +# (*)?*/ +# +# So .. the trivial example would be: +# +# /** +# * my_function +# **/ +# +# If the Description: header tag is omitted, then there must be a blank line +# after the last parameter specification. +# e.g. +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * +# * Does my stuff explained. +# */ +# +# or, could also use: +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * Description: Does my stuff explained. +# */ +# etc. +# +# Beside functions you can also write documentation for structs, unions, +# enums and typedefs. Instead of the function name you must write the name +# of the declaration; the struct/union/enum/typedef must always precede +# the name. Nesting of declarations is not supported. +# Use the argument mechanism to document members or constants. +# e.g. +# /** +# * struct my_struct - short description +# * @a: first member +# * @b: second member +# * +# * Longer description +# */ +# struct my_struct { +# int a; +# int b; +# /* private: */ +# int c; +# }; +# +# All descriptions can be multiline, except the short function description. +# +# You can also add additional sections. When documenting kernel functions you +# should document the "Context:" of the function, e.g. whether the functions +# can be called form interrupts. Unlike other sections you can end it with an +# empty line. +# Example-sections should contain the string EXAMPLE so that they are marked +# appropriately in DocBook. +# +# Example: +# /** +# * user_function - function that can only be called in user context +# * @a: some argument +# * Context: !in_interrupt() +# * +# * Some description +# * Example: +# * user_function(22); +# */ +# ... +# +# +# All descriptive text is further processed, scanning for the following special +# patterns, which are highlighted appropriately. +# +# 'funcname()' - function +# '$ENVVAR' - environmental variable +# '&struct_name' - name of a structure (up to two words including 'struct') +# '@parameter' - name of a parameter +# '%CONST' - name of a constant. + +my $errors = 0; +my $warnings = 0; +my $anon_struct_union = 0; + +# match expressions used to find embedded type information +my $type_constant = '\%([-_\w]+)'; +my $type_func = '(\w+)\(\)'; +my $type_param = '\@(\w+)'; +my $type_struct = '\&((struct\s*)*[_\w]+)'; +my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; +my $type_env = '(\$\w+)'; + +# Output conversion substitutions. +# One for each output format + +# these work fairly well +my %highlights_html = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct_xml, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $local_lt = "\\\\\\\\lt:"; +my $local_gt = "\\\\\\\\gt:"; +my $blankline_html = $local_lt . "p" . $local_gt; # was "

" + +# XML, docbook format +my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1\$2", + $type_constant, "\$1", + $type_func, "\$1", + $type_struct_xml, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n"; + +# gnome, docbook format +my %highlights_gnome = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_env, "\$1", + $type_param, "\$1" ); +my $blankline_gnome = "\n"; + +# these are pretty rough +my %highlights_man = ( $type_constant, "\$1", + $type_func, "\\\\fB\$1\\\\fP", + $type_struct, "\\\\fI\$1\\\\fP", + $type_param, "\\\\fI\$1\\\\fP" ); +my $blankline_man = ""; + +# text-mode +my %highlights_text = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +my $blankline_text = ""; + + +sub usage { + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; + print " c source file(s) > outputfile\n"; + print " -v : verbose output, more warnings & other info listed\n"; + exit 1; +} + +# read arguments +if ($#ARGV==-1) { + usage(); +} + +my $verbose = 0; +my $output_mode = "man"; +my $no_doc_sections = 0; +my %highlights = %highlights_man; +my $blankline = $blankline_man; +my $modulename = "Kernel API"; +my $function_only = 0; +my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', + 'July', 'August', 'September', 'October', + 'November', 'December')[(localtime)[4]] . + " " . ((localtime)[5]+1900); + +# Essentially these are globals +# They probably want to be tidied up made more localised or summat. +# CAVEAT EMPTOR! Some of the others I localised may not want to be which +# could cause "use of undefined value" or other bugs. +my ($function, %function_table,%parametertypes,$declaration_purpose); +my ($type,$declaration_name,$return_type); +my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map); + +if (defined($ENV{'KBUILD_VERBOSE'})) { + $verbose = "$ENV{'KBUILD_VERBOSE'}"; +} + +# Generated docbook code is inserted in a template at a point where +# docbook v3.1 requires a non-zero sequence of RefEntry's; see: +# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html +# We keep track of number of generated entries and generate a dummy +# if needs be to ensure the expanded template can be postprocessed +# into html. +my $section_counter = 0; + +my $lineprefix=""; + +# states +# 0 - normal code +# 1 - looking for function name +# 2 - scanning field start. +# 3 - scanning prototype. +# 4 - documentation block +my $state; +my $in_doc_sect; + +#declaration types: can be +# 'function', 'struct', 'union', 'enum', 'typedef', 'probe', 'sfunction' +my $decl_type; + +my $doc_special = "\@\%\$\&"; + +my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. +my $doc_end = '\*/'; +my $doc_com = '\s*\*\s*'; +my $doc_decl = $doc_com.'(\w+)'; +my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)'; +my $doc_content = $doc_com.'(.*)'; +my $doc_block = $doc_com.'DOC:\s*(.*)?'; + +my %constants; +my %parameterdescs; +my @parameterlist; +my %sections; +my @sectionlist; + +my $contents = ""; +my $section_default = "Description"; # default section +my $section_intro = "Introduction"; +my $section = $section_default; +my $section_context = "Context"; + +my $undescribed = "-- undescribed --"; + +reset_state(); + +while ($ARGV[0] =~ m/^-(.*)/) { + my $cmd = shift @ARGV; + if ($cmd eq "-html") { + $output_mode = "html"; + %highlights = %highlights_html; + $blankline = $blankline_html; + } elsif ($cmd eq "-man") { + $output_mode = "man"; + %highlights = %highlights_man; + $blankline = $blankline_man; + } elsif ($cmd eq "-text") { + $output_mode = "text"; + %highlights = %highlights_text; + $blankline = $blankline_text; + } elsif ($cmd eq "-docbook") { + $output_mode = "xml"; + %highlights = %highlights_xml; + $blankline = $blankline_xml; + } elsif ($cmd eq "-gnome") { + $output_mode = "gnome"; + %highlights = %highlights_gnome; + $blankline = $blankline_gnome; + } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document + $modulename = shift @ARGV; + } elsif ($cmd eq "-function") { # to only output specific functions + $function_only = 1; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-nofunction") { # to only output specific functions + $function_only = 2; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-v") { + $verbose = 1; + } elsif (($cmd eq "-h") || ($cmd eq "--help")) { + usage(); + } elsif ($cmd eq '-filelist') { + $filelist = shift @ARGV; + } elsif ($cmd eq '-no-doc-sections') { + $no_doc_sections = 1; + } +} + +# get kernel version from env +sub get_kernel_version() { + my $version = 'unknown kernel version'; + + if (defined($ENV{'KERNELVERSION'})) { + $version = $ENV{'KERNELVERSION'}; + } + return $version; +} +my $kernelversion = get_kernel_version(); + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +my $dohighlight = ""; +foreach my $pattern (keys %highlights) { +# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n"; + $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; +} + +## +# dumps section contents to arrays/hashes intended for that purpose. +# +sub dump_section { + my $file = shift; + my $name = shift; + my $contents = join "\n", @_; + + if ($name =~ m/$type_constant/) { + $name = $1; +# print STDERR "constant section '$1' = '$contents'\n"; + $constants{$name} = $contents; + } elsif ($name =~ m/$type_param/) { +# print STDERR "parameter def '$1' = '$contents'\n"; + $name = $1; + $parameterdescs{$name} = $contents; + } else { +# print STDERR "other section '$name' = '$contents'\n"; + if (defined($sections{$name}) && ($sections{$name} ne "")) { + print STDERR "Error(${file}:$.): duplicate section name '$name'\n"; + ++$errors; + } + $sections{$name} = $contents; + push @sectionlist, $name; + } +} + +## +# dump DOC: section after checking that it should go out +# +sub dump_doc_section { + my $file = shift; + my $name = shift; + my $contents = join "\n", @_; + + if ($no_doc_sections) { + return; + } + + if (($function_only == 0) || + ( $function_only == 1 && defined($function_table{$name})) || + ( $function_only == 2 && !defined($function_table{$name}))) + { + dump_section($file, $name, $contents); + output_blockhead({'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'module' => $modulename, + 'content-only' => ($function_only != 0), }); + } +} + +## +# output function +# +# parameterdescs, a hash. +# function => "function name" +# parameterlist => @list of parameters +# parameterdescs => %parameter descriptions +# sectionlist => @list of sections +# sections => %section descriptions +# + +sub output_highlight { + my $contents = join "\n",@_; + my $line; + +# DEBUG +# if (!defined $contents) { +# use Carp; +# confess "output_highlight got called with no args?\n"; +# } + + if ($output_mode eq "html" || $output_mode eq "xml") { + $contents = local_unescape($contents); + # convert data read & converted thru xml_escape() into &xyz; format: + $contents =~ s/\\\\\\/&/g; + } +# print STDERR "contents b4:$contents\n"; + eval $dohighlight; + die $@ if $@; +# print STDERR "contents af:$contents\n"; + + foreach $line (split "\n", $contents) { + if ($line eq ""){ + print $lineprefix, local_unescape($blankline); + } else { + $line =~ s/\\\\\\/\&/g; + if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { + print "\\&$line"; + } else { + print $lineprefix, $line; + } + } + print "\n"; + } +} + +#output sections in html +sub output_section_html(%) { + my %args = %{$_[0]}; + my $section; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
\n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } +} + +# output enum in html +sub output_enum_html(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "

enum ".$args{'enum'}."

\n"; + + print "enum ".$args{'enum'}." {
\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print " ".$parameter.""; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + print "
"; + } + print "};
\n"; + + print "

Constants

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output typedef in html +sub output_typedef_html(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "

typedef ".$args{'typedef'}."

\n"; + + print "typedef ".$args{'typedef'}."\n"; + output_section_html(@_); + print "
\n"; +} + +# output struct in html +sub output_struct_html(%) { + my %args = %{$_[0]}; + my ($parameter); + + print "

".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."

\n"; + print "".$args{'type'}." ".$args{'struct'}." {
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print "$parameter
\n"; + next; + } + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "    $1$parameter) ($2);
\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield + print "    $1 $parameter$2;
\n"; + } else { + print "    $type $parameter;
\n"; + } + } + print "};
\n"; + + print "

Members

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output function in html +sub output_function_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print "

" .$args{'function'}." - ".$args{'purpose'}."

\n"; + print "".$args{'functiontype'}."\n"; + print "".$args{'function'}."\n"; + print "("; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "$1$parameter) ($2)"; + } else { + print "".$type." ".$parameter.""; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + } + print ")\n"; + + print "

Arguments

\n"; + print "
\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print "
".$parameter."\n"; + print "
"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + print "
\n"; + output_section_html(@_); + print "
\n"; +} + +# output probe in html +sub output_probe_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + +} + +# output sfunction in html +sub output_sfunction_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + +} + +# output DOC: block header in html +sub output_blockhead_html(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + foreach $section (@{$args{'sectionlist'}}) { + print "

$section

\n"; + print "
    \n"; + output_highlight($args{'sections'}{$section}); + print "
\n"; + } + print "
\n"; +} + +sub output_section_xml(%) { + my %args = %{$_[0]}; + my $section; + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n"; + print "$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + print "\n"; + } + output_highlight($args{'sections'}{$section}); + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + print "\n"; + } + print "\n"; + } +} + +# output function in XML DocBook +sub output_function_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; + print "\n"; + print " ".$args{'function'}."\n"; + print " 9\n"; + print " " . $kernelversion . "\n"; + print "\n"; + print "\n"; + print " ".$args{'function'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." \n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1$parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + print "\n"; + + # print parameters + print "\n Arguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + output_section_xml(@_); + print "\n\n"; +} + +# output struct in XML DocBook +sub output_struct_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $id; + + $id = "API-struct-".$args{'struct'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; + print "\n"; + print " ".$args{'type'}." ".$args{'struct'}."\n"; + print " 9\n"; + print " " . $kernelversion . "\n"; + print "\n"; + print "\n"; + print " ".$args{'type'}." ".$args{'struct'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print "$parameter\n"; + next; + } + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + defined($args{'parameterdescs'}{$parameter_name}) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter) ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield + print " $1 $parameter$2;\n"; + } else { + print " ".$type." ".$parameter.";\n"; + } + } + print "};"; + print " \n"; + print "\n"; + + print " \n"; + print " Members\n"; + + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + defined($args{'parameterdescs'}{$parameter_name}) || next; + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print " "; + print " $parameter\n"; + print " \n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n"; + print " \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print " \n"; + + output_section_xml(@_); + + print "\n\n"; +} + +# output enum in XML DocBook +sub output_enum_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-enum-".$args{'enum'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; + print "\n"; + print " enum ".$args{'enum'}."\n"; + print " 9\n"; + print " " . $kernelversion . "\n"; + print "\n"; + print "\n"; + print " enum ".$args{'enum'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print " $parameter"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ","; + } + print "\n"; + } + print "};"; + print " \n"; + print "\n"; + + print "\n"; + print " Constants\n"; + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " "; + print " $parameter\n"; + print " \n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n"; + print " \n"; + } + print " \n"; + print "\n"; + + output_section_xml(@_); + + print "\n\n"; +} + +# output typedef in XML DocBook +sub output_typedef_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $id; + + $id = "API-typedef-".$args{'typedef'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; + print "\n"; + print " typedef ".$args{'typedef'}."\n"; + print " 9\n"; + print "\n"; + print "\n"; + print " typedef ".$args{'typedef'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " typedef ".$args{'typedef'}.";\n"; + print "\n"; + + output_section_xml(@_); + + print "\n\n"; +} + +# output in XML DocBook +sub output_blockhead_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + my $id = $args{'module'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + if (!$args{'content-only'}) { + print "\n $section\n"; + } + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + print "\n"; + } + output_highlight($args{'sections'}{$section}); + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + print ""; + } + if (!$args{'content-only'}) { + print "\n\n"; + } + } + + print "\n\n"; +} + +# output in XML DocBook +sub output_probe_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'probe'}; + $id =~ s/[^A-Za-z0-9]/-/g; + print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; + print "\n"; + print " ".$args{'probe'}."\n"; + print " 5\n"; + print " " . $kernelversion . "\n"; + print "\n"; + print "\n"; + print " ".$args{'probe'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print "".$args{'probe'}." \n"; + print "\n"; + + # print parameters + print "\n Values\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + output_section_xml(@_); + print "\n\n"; +} + +# output in XML DocBook +sub output_sfunction_xml(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = "API-".$args{'sfunction'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print "\n"; + print " LINUX\n"; + print " Kernel Hackers Manual\n"; + print " $man_date\n"; + print "\n"; + print "\n"; + print " ".$args{'sfunction'}."\n"; + print " 5\n"; + print " " . $kernelversion . "\n"; + print "\n"; + print "\n"; + print " ".$args{'sfunction'}."\n"; + print " \n"; + print " "; + output_highlight ($args{'purpose'}); + print " \n"; + print "\n"; + + print "\n"; + print " Synopsis\n"; + print " \n"; + print " ".$args{'sfunction'}.":"; + print $args{'functiontype'}."(\n"; + + $count = $#{$args{'parameterlist'}}; + if ($count >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + print " ".$parameter.":".$type; + $count -= 1; + if ($count >= 0) { print ",\n"; } + } + } else { + print " "; + } + print "\n );\n\n"; + print "\n"; + + # print parameters + print "\n Arguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " \n $parameter\n"; + print " \n \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n \n \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + print "\n"; + + output_section_xml(@_); + print "\n\n"; +} + +# output in XML DocBook +sub output_function_gnome { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}."-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "\n"; + print " ".$args{'function'}."\n"; + + print " \n"; + print " ".$args{'functiontype'}." "; + print "".$args{'function'}." "; + print "\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print " $1 $parameter)\n"; + print " $2\n"; + } else { + print " ".$type; + print " $parameter\n"; + } + } + } else { + print " \n"; + } + print " \n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " \n"; + print "\n"; + print "\n"; + print "\n"; + print "\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print " $parameter\n"; + print " \n"; + $lineprefix=" "; + output_highlight($args{'parameterdescs'}{$parameter_name}); + print " \n"; + } + print " \n"; + } else { + print " \n None\n \n"; + } + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "\n $section\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print "\n"; + output_highlight($args{'sections'}{$section}); + print "\n"; + if ($section =~ m/EXAMPLE/i) { + print "\n"; + } else { + } + print " \n"; + } + + print "\n\n"; +} + +## +# output function in man +sub output_function_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'function'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + if ($args{'functiontype'} ne "") { + print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + } else { + print ".B \"".$args{'function'}."\n"; + } + $count = 0; + my $parenth = "("; + my $post = ","; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count == $#{$args{'parameterlist'}}) { + $post = ");"; + } + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n"; + } + $count++; + $parenth = ""; + } + + print ".SH ARGUMENTS\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"", uc $section, "\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output enum in man +sub output_enum_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + print ".br\n.BI \" $parameter\"\n"; + if ($count == $#{$args{'parameterlist'}}) { + print "\n};\n"; + last; + } + else { + print ", \n.br\n"; + } + $count++; + } + + print ".SH Constants\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output struct in man +sub output_struct_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n"; + + print ".SH SYNOPSIS\n"; + print $args{'type'}." ".$args{'struct'}." {\n.br\n"; + + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print ".BI \"$parameter\"\n.br\n"; + next; + } + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield + print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n"; + } + print "\n.br\n"; + } + print "};\n.br\n"; + + print ".SH Members\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print ".IP \"".$parameter."\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output typedef in man +sub output_typedef_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +sub output_blockhead_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output probe in man +sub output_probe_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + +} + +## +# output sfunction in man +sub output_sfunction_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + +} + +## +# output in text +sub output_function_text(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $start; + + print "Name:\n\n"; + print $args{'function'}." - ".$args{'purpose'}."\n"; + + print "\nSynopsis:\n\n"; + if ($args{'functiontype'} ne "") { + $start = $args{'functiontype'}." ".$args{'function'}." ("; + } else { + $start = $args{'function'}." ("; + } + print $start; + + my $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1.$parameter.") (".$2; + } else { + print $type." ".$parameter; + } + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + print " " x length($start); + } else { + print ");\n\n"; + } + } + + print "Arguments:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n"; + } + output_section_text(@_); +} + +#output sections in text +sub output_section_text(%) { + my %args = %{$_[0]}; + my $section; + + print "\n"; + foreach $section (@{$args{'sectionlist'}}) { + print "$section:\n\n"; + output_highlight($args{'sections'}{$section}); + } + print "\n\n"; +} + +# output enum in text +sub output_enum_text(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "Enum:\n\n"; + + print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n"; + print "enum ".$args{'enum'}." {\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print "\t$parameter"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ","; + } + print "\n"; + } + print "};\n\n"; + + print "Constants:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "$parameter\n\t"; + print $args{'parameterdescs'}{$parameter}."\n"; + } + + output_section_text(@_); +} + +# output typedef in text +sub output_typedef_text(%) { + my %args = %{$_[0]}; + my ($parameter); + my $count; + print "Typedef:\n\n"; + + print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n"; + output_section_text(@_); +} + +# output struct as text +sub output_struct_text(%) { + my %args = %{$_[0]}; + my ($parameter); + + print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n"; + print $args{'type'}." ".$args{'struct'}." {\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + if ($parameter =~ /^#/) { + print "$parameter\n"; + next; + } + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print "\t$1 $parameter) ($2);\n"; + } elsif ($type =~ m/^(.*?)\s*(:.*)/) { + # bitfield + print "\t$1 $parameter$2;\n"; + } else { + print "\t".$type." ".$parameter.";\n"; + } + } + print "};\n\n"; + + print "Members:\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print "$parameter\n\t"; + print $args{'parameterdescs'}{$parameter_name}."\n"; + } + print "\n"; + output_section_text(@_); +} + +sub output_blockhead_text(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + print " $section:\n"; + print " -> "; + output_highlight($args{'sections'}{$section}); + } +} + +# output probe as text +sub output_probe_text(%) { + my %args = %{$_[0]}; + my ($parameter); + +} + +# output sfunction as text +sub output_sfunction_text(%) { + my %args = %{$_[0]}; + my ($parameter); + +} + +## +# generic output function for all types (function, struct/union, typedef, enum); +# calls the generated, variable output_ function name based on +# functype and output_mode +sub output_declaration { + no strict 'refs'; + my $name = shift; + my $functype = shift; + my $func = "output_${functype}_$output_mode"; + if (($function_only==0) || + ( $function_only == 1 && defined($function_table{$name})) || + ( $function_only == 2 && !defined($function_table{$name}))) + { + &$func(@_); + $section_counter++; + } +} + +## +# generic output function - calls the right one based on current output mode. +sub output_blockhead { + no strict 'refs'; + my $func = "output_blockhead_".$output_mode; + &$func(@_); + $section_counter++; +} + +sub dump_probe($$) { + my $x = shift; + my $file = shift; + + @parameterlist = keys %parameterdescs; + + $declaration_name = $x; + output_declaration($declaration_name, + 'probe', + {'probe' => $declaration_name, + 'parameterlist' => \@parameterlist, + 'module' => $modulename, + 'parameterdescs' => \%parameterdescs, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); +} + +## +# takes a declaration (struct, union, enum, typedef) and +# invokes the right handler. NOT called for functions. +sub dump_declaration($$) { + no strict 'refs'; + my ($prototype, $file) = @_; + my $func = "dump_".$decl_type; + &$func(@_); +} + +sub dump_union($$) { + dump_struct(@_); +} + +sub dump_struct($$) { + my $x = shift; + my $file = shift; + + if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) { + $declaration_name = $2; + my $members = $3; + + # ignore embedded structs or unions + $members =~ s/{.*}//g; + + # ignore members marked private: + $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos; + $members =~ s/\/\*.*?private:.*//gos; + # strip comments: + $members =~ s/\/\*.*?\*\///gos; + + create_parameterlist($members, ';', $file); + + output_declaration($declaration_name, + 'struct', + {'struct' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose, + 'type' => $decl_type + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse struct or union!\n"; + ++$errors; + } +} + +sub dump_enum($$) { + my $x = shift; + my $file = shift; + + $x =~ s@/\*.*?\*/@@gos; # strip comments. + if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { + $declaration_name = $1; + my $members = $2; + + foreach my $arg (split ',', $members) { + $arg =~ s/^\s*(\w+).*/$1/; + push @parameterlist, $arg; + if (!$parameterdescs{$arg}) { + $parameterdescs{$arg} = $undescribed; + print STDERR "Warning(${file}:$.): Enum value '$arg' ". + "not described in enum '$declaration_name'\n"; + } + + } + + output_declaration($declaration_name, + 'enum', + {'enum' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse enum!\n"; + ++$errors; + } +} + +sub dump_typedef($$) { + my $x = shift; + my $file = shift; + + $x =~ s@/\*.*?\*/@@gos; # strip comments. + while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { + $x =~ s/\(*.\)\s*;$/;/; + $x =~ s/\[*.\]\s*;$/;/; + } + + if ($x =~ /typedef.*\s+(\w+)\s*;/) { + $declaration_name = $1; + + output_declaration($declaration_name, + 'typedef', + {'typedef' => $declaration_name, + 'module' => $modulename, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "Error(${file}:$.): Cannot parse typedef!\n"; + ++$errors; + } +} + +sub create_parameterlist($$$) { + my $args = shift; + my $splitter = shift; + my $file = shift; + my $type; + my $param; + + # temporarily replace commas inside function pointer definition + while ($args =~ /(\([^\),]+),/) { + $args =~ s/(\([^\),]+),/$1#/g; + } + + foreach my $arg (split($splitter, $args)) { + # strip comments + $arg =~ s/\/\*.*\*\///; + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; + $arg =~ s/\s+/ /; + + if ($arg =~ /^#/) { + # Treat preprocessor directive as a typeless variable just to fill + # corresponding data structures "correctly". Catch it later in + # output_* subs. + push_parameter($arg, "", $file); + } elsif ($arg =~ m/\(.+\)\s*\(/) { + # pointer-to-function + $arg =~ tr/#/,/; + $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/; + $param = $1; + $type = $arg; + $type =~ s/([^\(]+\(\*?)\s*$param/$1/; + push_parameter($param, $type, $file); + } elsif ($arg) { + $arg =~ s/\s*:\s*/:/g; + $arg =~ s/\s*\[/\[/g; + + my @args = split('\s*,\s*', $arg); + if ($args[0] =~ m/\*/) { + $args[0] =~ s/(\*+)\s*/ $1/; + } + + my @first_arg; + if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) { + shift @args; + push(@first_arg, split('\s+', $1)); + push(@first_arg, $2); + } else { + @first_arg = split('\s+', shift @args); + } + + unshift(@args, pop @first_arg); + $type = join " ", @first_arg; + + foreach $param (@args) { + if ($param =~ m/^(\*+)\s*(.*)/) { + push_parameter($2, "$type $1", $file); + } + elsif ($param =~ m/(.*?):(\d+)/) { + if ($type ne "") { # skip unnamed bit-fields + push_parameter($1, "$type:$2", $file) + } + } + else { + push_parameter($param, $type, $file); + } + } + } + } +} + +sub create_sparameterlist($$$) { + my $args = shift; + my $splitter = shift; + my $file = shift; + my $type; + my $param; + + foreach my $arg (split($splitter, $args)) { + if ($arg =~ m/s*([\w]+)\s*:?\s*([\w]*)/) { + $param = $1; + $type = $2; + push_parameter($param, $type, $file); + } else { + print STDERR "Error(${file}:$.): problem parsing parameters: '$prototype'\n"; + ++$errors; + return; + } + } +} + +sub push_parameter($$$) { + my $param = shift; + my $type = shift; + my $file = shift; + + if (($anon_struct_union == 1) && ($type eq "") && + ($param eq "}")) { + return; # ignore the ending }; from anon. struct/union + } + + $anon_struct_union = 0; + my $param_name = $param; + $param_name =~ s/\[.*//; + + if ($type eq "" && $param =~ /\.\.\.$/) + { + $type=""; + $parameterdescs{$param} = "variable arguments"; + } + elsif ($type eq "" && ($param eq "" or $param eq "void")) + { + $type=""; + $param="void"; + $parameterdescs{void} = "no arguments"; + } + elsif ($type eq "" && ($param eq "struct" or $param eq "union")) + # handle unnamed (anonymous) union or struct: + { + $type = $param; + $param = "{unnamed_" . $param . "}"; + $parameterdescs{$param} = "anonymous\n"; + $anon_struct_union = 1; + } + + # warn if parameter has no description + # (but ignore ones starting with # as these are not parameters + # but inline preprocessor statements); + # also ignore unnamed structs/unions; + if (!$anon_struct_union) { + if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) { + + $parameterdescs{$param_name} = $undescribed; + + if (($type eq 'function') || ($type eq 'enum')) { + print STDERR "Warning(${file}:$.): Function parameter ". + "or member '$param' not " . + "described in '$declaration_name'\n"; + } + print STDERR "Warning(${file}:$.):". + " No description found for parameter '$param'\n"; + ++$warnings; + } + } + + push @parameterlist, $param; + $parametertypes{$param} = $type; +} + +## +# takes a function prototype and the name of the current file being +# processed and spits out all the details stored in the global +# arrays/hashes. +sub dump_function($$) { + my $prototype = shift; + my $file = shift; + + $prototype =~ s/^static +//; + $prototype =~ s/^extern +//; + $prototype =~ s/^asmlinkage +//; + $prototype =~ s/^inline +//; + $prototype =~ s/^__inline__ +//; + $prototype =~ s/^__inline +//; + $prototype =~ s/^__always_inline +//; + $prototype =~ s/^noinline +//; + $prototype =~ s/__devinit +//; + $prototype =~ s/__init +//; + $prototype =~ s/^#\s*define\s+//; #ak added + $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//; + + # Yes, this truly is vile. We are looking for: + # 1. Return type (may be nothing if we're looking at a macro) + # 2. Function name + # 3. Function parameters. + # + # All the while we have to watch out for function pointer parameters + # (which IIRC is what the two sections are for), C types (these + # regexps don't even start to express all the possibilities), and + # so on. + # + # If you mess with these regexps, it's a good idea to check that + # the following functions' documentation still comes out right: + # - parport_register_device (function pointer parameters) + # - atomic_set (macro) + # - pci_match_device, __copy_to_user (long return type) + + if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $return_type = $1; + $declaration_name = $2; + my $args = $3; + + create_parameterlist($args, ',', $file); + } else { + print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; + ++$errors; + return; + } + + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); +} + +## +# takes a stap function prototype and the name of the current file being +# processed and spits out all the details stored in the global +# arrays/hashes. +sub dump_sfunction($$) { + my $prototype = shift; + my $file = shift; + + if ($prototype =~ m/^function\s+([\w]+)\s*:?\s*([\w]*)\s*\(([^\{]*)\)/) { + $declaration_name = $1; + $return_type = $2; + my $args = $3; + + create_sparameterlist($args, ',', $file); + } else { + print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; + ++$errors; + return; + } + + output_declaration($declaration_name, + 'sfunction', + {'sfunction' => $declaration_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); +} + +sub process_file($); + +# Read the file that maps relative names to absolute names for +# separate source and object directories and for shadow trees. +if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { + my ($relname, $absname); + while() { + chop(); + ($relname, $absname) = (split())[0..1]; + $relname =~ s:^/+::; + $source_map{$relname} = $absname; + } + close(SOURCE_MAP); +} + +if ($filelist) { + open(FLIST,"<$filelist") or die "Can't open file list $filelist"; + while() { + chop; + process_file($_); + } +} + +foreach (@ARGV) { + chomp; + process_file($_); +} +if ($verbose && $errors) { + print STDERR "$errors errors\n"; +} +if ($verbose && $warnings) { + print STDERR "$warnings warnings\n"; +} + +exit($errors); + +sub reset_state { + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + + $state = 0; +} + +sub process_state3_function($$) { + my $x = shift; + my $file = shift; + + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) { + # do nothing + } + elsif ($x =~ /([^\{]*)/) { + $prototype .= $1; + } + if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) { + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^\s+@@gos; # strip leading spaces + dump_function($prototype,$file); + reset_state(); + } +} + +sub process_state3_type($$) { + my $x = shift; + my $file = shift; + + $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $x =~ s@^\s+@@gos; # strip leading spaces + $x =~ s@\s+$@@gos; # strip trailing spaces + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =~ /^#/) { + # To distinguish preprocessor directive from regular declaration later. + $x .= ";"; + } + + while (1) { + if ( $x =~ /([^{};]*)([{};])(.*)/ ) { + $prototype .= $1 . $2; + ($2 eq '{') && $brcount++; + ($2 eq '}') && $brcount--; + if (($2 eq ';') && ($brcount == 0)) { + dump_declaration($prototype,$file); + reset_state(); + last; + } + $x = $3; + } else { + $prototype .= $x; + last; + } + } +} + +sub process_state3_sfunction($$) { + my $x = shift; + my $file = shift; + + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) { + # do nothing + } + elsif ($x =~ /([^\{]*)/) { + $prototype .= $1; + } + + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^\s+@@gos; # strip leading spaces + dump_sfunction($prototype,$file); + reset_state(); +} + +sub process_state3_probe($$) { + my $prototype = shift; + my $file = shift; + + $prototype =~ s@/probe/@@o; # strip off leading 'probe' + $prototype =~ s@^\s+@@gos; # strip leading spaces + dump_probe($prototype,$file); + reset_state(); +} + +# xml_escape: replace <, >, and & in the text stream; +# +# however, formatting controls that are generated internally/locally in the +# kernel-doc script are not escaped here; instead, they begin life like +# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings +# are converted to their mnemonic-expected output, without the 4 * '\' & ':', +# just before actual output; (this is done by local_unescape()) +sub xml_escape($) { + my $text = shift; + if (($output_mode eq "text") || ($output_mode eq "man")) { + return $text; + } + $text =~ s/\&/\\\\\\amp;/g; + $text =~ s/\/\\\\\\gt;/g; + return $text; +} + +# convert local escape strings to html +# local escape strings look like: '\\\\menmonic:' (that's 4 backslashes) +sub local_unescape($) { + my $text = shift; + if (($output_mode eq "text") || ($output_mode eq "man")) { + return $text; + } + $text =~ s/\\\\\\\\lt://g; + return $text; +} + +sub process_file($) { + my $file; + my $identifier; + my $func; + my $descr; + my $initial_section_counter = $section_counter; + + if (defined($ENV{'SRCTREE'})) { + $file = "$ENV{'SRCTREE'}" . "/" . "@_"; + } + else { + $file = "@_"; + } + if (defined($source_map{$file})) { + $file = $source_map{$file}; + } + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + $section_counter = 0; + while () { + if ($state == 0) { + if (/$doc_start/o) { + $state = 1; # next line is always the function name + $in_doc_sect = 0; + } + } elsif ($state == 1) { # this line is the function name (always) + if (/$doc_block/o) { + $state = 4; + $contents = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_decl/o) { + $identifier = $1; + if (/\s*([\w\s\.]+?)\s*-/) { + $identifier = $1; + } + + $state = 2; + if (/-(.*)/) { + # strip leading/trailing/multiple spaces + $descr= $1; + $descr =~ s/^\s*//; + $descr =~ s/\s*$//; + $descr =~ s/\s+/ /; + $declaration_purpose = xml_escape($descr); + } else { + $declaration_purpose = ""; + } + + if (($declaration_purpose eq "") && $verbose) { + print STDERR "Warning(${file}:$.): missing initial short description on line:\n"; + print STDERR $_; + ++$warnings; + } + + if ($identifier =~ m/^struct/) { + $decl_type = 'struct'; + } elsif ($identifier =~ m/^union/) { + $decl_type = 'union'; + } elsif ($identifier =~ m/^enum/) { + $decl_type = 'enum'; + } elsif ($identifier =~ m/^typedef/) { + $decl_type = 'typedef'; + } elsif ($identifier =~ m/^probe/) { + $decl_type = 'probe'; + } elsif ($identifier =~ m/^sfunction/) { + $decl_type = 'sfunction'; + } else { + $decl_type = 'function'; + } + + if ($verbose) { + print STDERR "Info(${file}:$.): Scanning doc for $decl_type $identifier\n"; + } + } else { + print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.", + " - I thought it was a doc line\n"; + ++$warnings; + $state = 0; + } + } elsif ($state == 2) { # look for head: lines, and include content + if (/$doc_sect/o) { + $newsection = $1; + $newcontents = $2; + + if (($contents ne "") && ($contents ne "\n")) { + if (!$in_doc_sect && $verbose) { + print STDERR "Warning(${file}:$.): contents before sections\n"; + ++$warnings; + } + dump_section($file, $section, xml_escape($contents)); + $section = $section_default; + } + + $in_doc_sect = 1; + $contents = $newcontents; + if ($contents ne "") { + while ((substr($contents, 0, 1) eq " ") || + substr($contents, 0, 1) eq "\t") { + $contents = substr($contents, 1); + } + $contents .= "\n"; + } + $section = $newsection; + } elsif (/$doc_end/) { + + if ($contents ne "") { + dump_section($file, $section, xml_escape($contents)); + $section = $section_default; + $contents = ""; + } + # look for doc_com + + doc_end: + if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { + print STDERR "Warning(${file}:$.): suspicious ending line: $_"; + ++$warnings; + } + + $prototype = ""; + $state = 3; + $brcount = 0; +# print STDERR "end of doc comment, looking for prototype\n"; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "" && + ($section =~ m/^@/ || $section eq $section_context)) { + dump_section($file, $section, xml_escape($contents)); + $section = $section_default; + $contents = ""; + } else { + $contents .= $1."\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "Warning(${file}:$.): bad line: $_"; + ++$warnings; + } + } elsif ($state == 3) { # scanning for function '{' (end of prototype) + if ($decl_type eq 'function') { + process_state3_function($_, $file); + } elsif ($decl_type eq 'probe') { + process_state3_probe($identifier, $file); + } elsif ($decl_type eq 'sfunction') { + process_state3_sfunction($_, $file); + } else { + process_state3_type($_, $file); + } + } elsif ($state == 4) { + # Documentation block + if (/$doc_block/) { + dump_doc_section($file, $section, xml_escape($contents)); + $contents = ""; + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_end/) + { + dump_doc_section($file, $section, xml_escape($contents)); + $contents = ""; + $function = ""; + %constants = (); + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = 0; + } + elsif (/$doc_content/) + { + if ( $1 eq "" ) + { + $contents .= $blankline; + } + else + { + $contents .= $1 . "\n"; + } + } + } + } + if ($initial_section_counter == $section_counter) { + print STDERR "Warning(${file}): no structured comments found\n"; + if ($output_mode eq "xml") { + # The template wants at least one RefEntry here; make one. + print "\n"; + print " \n"; + print " \n"; + print " ${file}\n"; + print " \n"; + print " \n"; + print " Document generation inconsistency\n"; + print " \n"; + print " \n"; + print " \n"; + print " \n"; + print " Oops\n"; + print " \n"; + print " \n"; + print " \n"; + print " The template for this document tried to insert\n"; + print " the structured comment from the file\n"; + print " ${file} at this point,\n"; + print " but none was found.\n"; + print " This dummy section is inserted to allow\n"; + print " generation to continue.\n"; + print " \n"; + print " \n"; + print " \n"; + print "\n"; + } + } +} -- 1.5.6.5 --------------060802000209010300030008 Content-Type: text/x-patch; name="kernel-doc3.patch" Content-Transfer-Encoding: 7bit Content-Disposition: inline; filename="kernel-doc3.patch" Content-length: 35505 >From 9cd61407c728ffe78793f2265fd3d250660ec984 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Mon, 24 Nov 2008 10:51:46 -0500 Subject: [PATCH] Add context, timestamp, memory, and networking tapsets. --- doc/ChangeLog | 5 + doc/SystemTap_Tapset_Reference/tapsets.tmpl | 38 +++ tapset/ChangeLog | 7 + tapset/context.stp | 351 +++++++++++---------------- tapset/memory.stp | 267 ++++---------------- tapset/networking.stp | 76 ++----- tapset/timestamp.stp | 72 ++---- 7 files changed, 285 insertions(+), 531 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index ac2d01a..4106091 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,10 @@ 2008-11-24 Will Cohen + * SystemTap_Tapset_Reference/tapsets.tmpl: Add context, timestamp, + memory, and networking tapsets. + +2008-11-24 Will Cohen + * SystemTap_Tapset_Reference: Add kernel-doc based version. 2008-11-24 Will Cohen diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl index 8ae22ed..ccdba8c 100644 --- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl +++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl @@ -112,4 +112,42 @@ This is common among + + Context Functions + + The context functions provide additional information about the where + the event occurred. + These functions can provide information such as a backtrace + where the event occured + and the current register values for the processor. + +!Itapset/context.stp + + + + Timestamp Functions + + Each timestamp function returns a value to indicate when + the function is executed. + Thus, these returned values can be used to indicate + when an event occurs, provide an ordering for events, or compute + the amount of time elapsed between to time stamps. + +!Itapset/timestamp.stp + + + + Memory Tapset +!Itapset/memory.stp + + + + Networking Tapset + + This family of probe points is used to probe the activities of + network device. + +!Itapset/networking.stp + + diff --git a/tapset/ChangeLog b/tapset/ChangeLog index b63b1ac..20b564c 100644 --- a/tapset/ChangeLog +++ b/tapset/ChangeLog @@ -1,3 +1,10 @@ +2008-11-24 Will Cohen + + * context.stp: + * memory.stp: + * networking.stp: + * timestamp.stp: Change to use kernel-doc notation. + 2008-11-19 Jim Keniston * s390x/registers.stp: Fixed typo. diff --git a/tapset/context.stp b/tapset/context.stp index 3c87d1b..7505c60 100644 --- a/tapset/context.stp +++ b/tapset/context.stp @@ -7,37 +7,22 @@ // Public License (GPL); either version 2, or (at your option) any // later version. -/// -/// Context Functions -/// -/// The context functions provide additional information about the where -/// the event occurred. -/// These functions can provide information such as a backtrace -/// where the event occured -/// and the current register values for the processor. -/// -/// -/// print_regs() -/// print_regs -/// -/// Print a register dump. -/// -/// +/** + * sfunction print_regs - Print a register dump. + */ function print_regs () %{ if (CONTEXT->regs) { _stp_print_regs (CONTEXT->regs); } %} -/// -/// print_backtrace() -/// print_backtrace -/// -/// Equivalent to print_stack(backtrace()), -/// except that deeper stack nesting may be supported. Return nothing. -/// -/// +/** + * sfunction print_backtrace - Print stack back trace + * + * Equivalent to print_stack(backtrace()), + * except that deeper stack nesting may be supported. Return nothing. + */ function print_backtrace () %{ if (CONTEXT->regs) { _stp_stack_print(CONTEXT->regs, 1, CONTEXT->pi, MAXTRACE); @@ -46,14 +31,12 @@ function print_backtrace () %{ } %} -/// -/// backtrace:string() -/// backtrace -/// -/// Return a string of hex addresses that are a backtrace of the -/// stack. It may be truncated due to maximum string length. -/// -/// +/** + * sfunction backtrace - Hex backtrace of current stack + * + * Return a string of hex addresses that are a backtrace of the + * stack. It may be truncated due to maximum string length. + */ function backtrace:string () %{ /* pure */ if (CONTEXT->regs) _stp_stack_snprint (THIS->__retvalue, MAXSTRINGLEN, CONTEXT->regs, 0, CONTEXT->pi, MAXTRACE); @@ -61,46 +44,39 @@ function backtrace:string () %{ /* pure */ strlcpy (THIS->__retvalue, "", MAXSTRINGLEN); %} -/// -/// execname:string() -/// execname -/// -/// Return the name of the current process. -/// -/// +/** + * sfunction execname - Execname of current processes + * + * Return the name of the current process. + */ function execname:string () %{ /* pure */ strlcpy (THIS->__retvalue, current->comm, MAXSTRINGLEN); %} -/// -/// pid:long () -/// pid -/// -/// Return the id of the current process. -/// -/// +/** + * sfunction pid - Process ID of current process + * + * + * Return the id of the current process. + */ function pid:long () %{ /* pure */ THIS->__retvalue = current->tgid; %} -/// -/// tid:long() -/// tid -/// -/// Return the id of the current thread. -/// -/// +/** + * sfunction tid - Thread ID of current process + * + * Return the id of the current thread. + */ function tid:long () %{ /* pure */ THIS->__retvalue = current->pid; %} -/// -/// ppid:long() -/// ppid -/// -/// Return the id of the parent process. -/// -/// +/** + * sfunction ppid - Parent Process ID of current process + * + * Return the id of the parent process. + */ function ppid:long () %{ /* pure */ #if defined(STAPCONF_REAL_PARENT) THIS->__retvalue = current->real_parent->tgid; @@ -109,13 +85,11 @@ function ppid:long () %{ /* pure */ #endif %} -/// -/// pexecname:string() -/// pexecname -/// -/// Return the name of the parent process. -/// -/// +/** + * sfunction pexecname - Execname of the parent process. + * + * Return the name of the parent process. + */ function pexecname:string () %{ /* pure */ #if defined(STAPCONF_REAL_PARENT) strlcpy (THIS->__retvalue, current->real_parent->comm, MAXSTRINGLEN); @@ -124,46 +98,38 @@ function pexecname:string () %{ /* pure */ #endif %} -/// -/// gid:long() -/// gid -/// -/// Return the gid of the current process. -/// -/// +/** + * sfunction gid - Group ID of current process + * + * Return the gid of the current process. + */ function gid:long () %{ /* pure */ THIS->__retvalue = current->gid; %} -/// -/// egid:long() -/// egid -/// -/// Return the effective gid of the current process. -/// -/// +/** + * sfunction egid - Effective gid of the current process. + * + * Return the effective gid of the current process. + */ function egid:long () %{ /* pure */ THIS->__retvalue = current->egid; %} -/// -/// uid:long() -/// uid -/// -/// Return the uid of the current process. -/// -/// +/** + * sfunction uid -User ID of the current process. + * + * Return the uid of the current process. + */ function uid:long () %{ /* pure */ THIS->__retvalue = current->uid; %} -/// -/// euid:long() -/// euid -/// -/// Return the effective uid of the current process. -/// -/// +/** + * sfunction euid - Effective User ID of the current process. + * + * Return the effective uid of the current process. + */ function euid:long () %{ /* pure */ THIS->__retvalue = current->euid; %} @@ -173,29 +139,26 @@ function cpuid:long () %{ /* pure */ THIS->__retvalue = smp_processor_id(); %} -/// -/// cpu:long() -/// cpu -/// -/// Return the current cpu number. -/// -/// +/** + * sfunction cpu - The current cpu number. + * + * Return the current cpu number. + */ function cpu:long () %{ /* pure */ THIS->__retvalue = smp_processor_id(); %} -/// -/// print_stack(stk:string) -/// print_stack -/// -/// Perform a symbolic lookup of the addresses in the given string, -/// which is assumed to be the result of a prior call to -/// . -/// Print one line per address, including the address, the -/// name of the function containing the address, and an estimate of -/// its position within that function. Return nothing. -/// -/// +/** + * sfunction print_stack - Print out stack from string + * @stk: String with list of hexidecimal addresses. (FIXME) + * + * Perform a symbolic lookup of the addresses in the given string, + * which is assumed to be the result of a prior call to + * backtrace(). + * Print one line per address, including the address, the + * name of the function containing the address, and an estimate of + * its position within that function. Return nothing. + */ function print_stack(stk:string) %{ char *ptr = THIS->stk; char *tok = strsep(&ptr, " "); @@ -207,25 +170,21 @@ function print_stack(stk:string) %{ } %} -/// -/// pp:string() -/// pp -/// -/// Return the probe point associated with the currently running -/// probe handler, including alias and wildcard expansion effects. -/// -/// +/** + * sfunction pp - Current probe point + * + * Return the probe point associated with the currently running + * probe handler, including alias and wildcard expansion effects. + */ function pp:string () %{ /* pure */ strlcpy (THIS->__retvalue, CONTEXT->probe_point, MAXSTRINGLEN); %} -/// -/// probefunc:string() -/// probefunc -/// -/// Return the probe point's function name, if known. -/// -/// +/** + * sfunction probefunc - Function probed + * + * Return the probe point's function name, if known. + */ function probefunc:string () %{ /* pure */ char *ptr, *start; @@ -257,13 +216,11 @@ function probefunc:string () %{ /* pure */ } %} -/// -/// probemod:string() -/// probemod -/// -/// Return the probe point's module name, if known. -/// -/// +/** + * sfunction probemod - Module probed + * + * Return the probe point's module name, if known. + */ function probemod:string () %{ /* pure */ char *ptr, *start; @@ -282,27 +239,23 @@ function probemod:string () %{ /* pure */ } %} -/// -/// registers_valid:long() -/// registers_valid -/// -/// Return 1 if register() and u_register() can be used -/// in the current context, or 0 otherwise. -/// For example, registers_valid() returns 0 -/// when called from a begin or end probe. -/// -/// +/** + * sfunction registers_valid - Register information valid + * + * Return 1 if register() and u_register() can be used + * in the current context, or 0 otherwise. + * For example, registers_valid() returns 0 + * when called from a begin or end probe. + */ function registers_valid:long () %{ /* pure */ THIS->__retvalue = (CONTEXT->regs != NULL); %} -/// -/// user_mode:long() -/// user_mode -/// -/// Return 1 if the probe point occurred in user-mode. -/// -/// +/** + * sfunction user_mode - User Mode + * + * Return 1 if the probe point occurred in user-mode. + */ function user_mode:long () %{ /* pure */ /* currently a user-mode address? */ if (CONTEXT->regs) { #if defined(__i386__) || defined(__x86_64__) @@ -315,14 +268,12 @@ function user_mode:long () %{ /* pure */ /* currently a user-mode address? */ } %} -/// -/// is_return:long() -/// is_return -/// -/// Return 1 if the probe point is a return probe. -/// Deprecated. -/// -/// +/** + * sfunction is_return - Is return probe + * + * Return 1 if the probe point is a return probe. + * Deprecated. + */ function is_return:long () %{ /* pure */ if (CONTEXT->pi) THIS->__retvalue = 1; @@ -330,13 +281,11 @@ function is_return:long () %{ /* pure */ THIS->__retvalue = 0; %} -/// -/// target:long() -/// target -/// -/// Return the pid of the target process. -/// -/// +/** + * sfunction target - Target pid + * + * Return the pid of the target process. + */ function target:long () %{ /* pure */ THIS->__retvalue = _stp_target; %} @@ -363,50 +312,41 @@ function stp_pid:long () %{ /* pure */ THIS->__retvalue = _stp_pid; %} -/// -/// stack_size:long() -/// stack_size -/// -/// Return the size of the kernel stack. -/// -/// +/** + * sfunction stack_size - Size of kernel stack + * + * Return the size of the kernel stack. + */ function stack_size:long () %{ /* pure */ THIS->__retvalue = THREAD_SIZE; %} -/// -/// stack_used:long () -/// stack_used -/// -/// Return how many bytes are currently used in the kernel stack. -/// -/// +/** + * sfunction stack_used - Current amount of kernel stack used + * + * Return how many bytes are currently used in the kernel stack. + */ function stack_used:long () %{ /* pure */ char a; THIS->__retvalue = THREAD_SIZE - ((long)&a & (THREAD_SIZE-1)); %} -/// -/// stack_unused:long() -/// stack_unused -/// -/// Return how many bytes are currently available in the kernel stack. -/// -/// +/** + * sfunction stack_unused - Amount of kernel stack currently available + * + * Return how many bytes are currently available in the kernel stack. + */ function stack_unused:long () %{ /* pure */ char a; THIS->__retvalue = (long)&a & (THREAD_SIZE-1); %} -/// -/// caller_addr:long() -/// caller_addr -/// -/// Return the address of the calling function. -/// Works only for return probes at this time. -/// -/// -/// +/** + * sfunction caller_addr - Return caller address + * + * Return the address of the calling function. + * Works only for return probes at this time. + */ function caller_addr:long () %{ /* pure */ if (CONTEXT->pi) THIS->__retvalue = (int64_t)(long)_stp_ret_addr_r(CONTEXT->pi); @@ -414,14 +354,12 @@ function caller_addr:long () %{ /* pure */ THIS->__retvalue = 0; %} -/// -/// caller:string() -/// caller -/// -/// Return the address and name of the calling function. -/// Works only for return probes at this time. -/// -/// +/** + * sfunction caller - Return name and address of calling function + * + * Return the address and name of the calling function. + * Works only for return probes at this time. + */ function caller:string() %{ /* pure */ if (CONTEXT->pi) _stp_symbol_snprint( THIS->__retvalue, MAXSTRINGLEN, @@ -430,4 +368,3 @@ function caller:string() %{ /* pure */ strlcpy(THIS->__retvalue,"unknown",MAXSTRINGLEN); %} -/// diff --git a/tapset/memory.stp b/tapset/memory.stp index 03568ad..9370073 100644 --- a/tapset/memory.stp +++ b/tapset/memory.stp @@ -7,34 +7,14 @@ // Public License (GPL); either version 2, or (at your option) any // later version. -/// -/// Memory Tapset -/// -/// This family of probe points is used to probe page fault events. -/// It contains the following probe points: -/// - -/// -/// vm.pagefault -/// vm.pagefault -/// -/// Records that a page fault occurred. -/// The context is the process which triggered the fault. -/// -/// -/// Arguments: -/// address -/// -/// The address of the faulting memory access. -/// -/// -/// write_access -/// -/// Indicates whether this was a write. -/// -/// -/// -/// +/** + * probe vm.pagefault - Records that a page fault occurred. + * @address: The address of the faulting memory access. + * @write_access: Indicates whether this was a write. + * + * Context: The process which triggered the fault + * + */ probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?, kernel.function("handle_mm_fault@mm/memory.c") ? { @@ -42,61 +22,22 @@ probe vm.pagefault = kernel.function("__handle_mm_fault@mm/memory.c") ?, address = $address } -/// -/// vm.pagefault.return -/// vm.pagefault.return -/// -/// Records type of fault that occurred. -/// The context is the process which triggered the fault. -/// -/// -/// -/// Arguments: -/// fault_type -/// The possible values of fault_type are: -/// Fault values -/// -/// -/// -/// -/// -/// DefineValueReason -/// -/// -/// -/// VM_FAULT_OOM -/// 0 -/// out of memory -/// -/// -/// VM_FAULT_SIGBUS -/// 1 -/// if not oom, minor, or major fault, this val -/// -/// -/// VM_FAULT_MINOR -/// 2 -/// no blocking operation to handle fault -/// -/// -/// VM_FAULT_MAJOR -/// 3 -/// required blocking operation to handle fault -/// -/// -/// -///
-/// -/// -/// -/// +/** + * probe vm.pagefault.return - Records type of fault that occurred. + * @fault_type: 0 (VM_FAULT_OOM), 1 (VM_FAULT_SIGBUS), + * 2 (VM_FAULT_MINOR), and 3 (VM_FAULT_MAJOR) + */ probe vm.pagefault.return = kernel.function("__handle_mm_fault@mm/memory.c").return ?, kernel.function("handle_mm_fault@mm/memory.c").return ? { fault_type = $return } -/* Return which node the given address belongs to in a NUMA system */ +/** + * sfunction addr_to_node - Returns which NUMA node has the given address. + * @addr: The address of the faulting memory access. + * + */ function addr_to_node:long(addr:long) %{ /* pure */ int nid; int pfn = __pa(THIS->addr) >> PAGE_SHIFT; @@ -116,64 +57,32 @@ function _IS_ZERO_PAGE:long(from:long, vaddr:long) %{ /* pure */ %} -/// -/// vm.write_shared -/// vm.write_shared -/// -/// Fires when a process attempts to write to a shared page. -/// If a copy is necessary, this will be followed by a -/// . -/// The context is the process attempting the write. -/// -/// -/// -/// Arguments: -/// address -/// The address of the shared write. -/// -/// -/// +/** + * probe vm.write_shared - Write to shared page. + * @address: The address of the shared write. + * + * Context: + * The context is the process attempting the write. + * + * Fires when a process attempts to write to a shared page. + * If a copy is necessary, this will be followed by a + * vm.write_shared_copy. + */ probe vm.write_shared = kernel.function("do_wp_page") { address = $address } - -/// -/// vm.write_shared_copy -/// vm.write_shared_copy -/// -/// Fires when a write to a shared page requires a page copy. -/// This is always preceded by a . -/// The context is the process attempting the write. -/// -/// -/// -/// Arguments: -/// address -/// -/// The address of the shared write. -/// -/// -/// zero -/// -/// Boolean indicating whether it is a zero page -/// (can do a clear instead of a copy). -/// -/// -/// -/// -/* probe vm.write_shared_copy - * - * Fires when a write to a shared page requires a page copy. This is - * always preceded by a vm.shared_write. +/** + * probe vm.write_shared_copy- Page copy for shared page write. + * @address: the address of the shared write. + * @zero: boolean indicating whether it is a zero page + * (can do a clear instead of a copy). * * Context: * The process attempting the write. * - * Arguments: - * address - the address of the shared write. - * zero - boolean indicating whether it is a zero page - * (can do a clear instead of a copy). + * Fires when a write to a shared page requires a page copy. This is + * always preceded by a vm.shared_write. */ probe vm.write_shared_copy = kernel.function("copy_cow_page")? { address = $address @@ -181,34 +90,13 @@ probe vm.write_shared_copy = kernel.function("copy_cow_page")? { } -/// -/// vm.mmap -/// vm.mmap -/// -/// Fires when an mmap is requested. -/// The context is the process calling mmap. -/// -/// -/// -/// Arguments: -/// address -/// The requested address. -/// -/// length -/// The length of the memory segment. -/// -/// -/// -/* probe vm.mmap - * - * Fires when an mmap is requested. +/** + * probe vm.mmap - Fires when an mmap is requested. + * @address: the requested address + * @length: the length of the memory segment * * Context: * The process calling mmap. - * - * Arguments: - * address - the requested address - * length - the length of the memory segment */ probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? { address = $addr @@ -216,93 +104,40 @@ probe vm.mmap = kernel.function("do_mmap"), kernel.function("do_mmap2")? { } -/// -/// vm.munmap -/// vm.munmap -/// Fires when an munmap is requested. -/// -/// -/// Arguments: -/// address -/// The requested address. -/// -/// length -/// The length of the memory segment. -/// -/// -/// -/* probe vm.munmap - * - * Fires when an munmap is requested. +/** + * probe vm.munmap - Fires when an munmap is requested. + * @address: the requested address + * @length: the length of the memory segment * * Context: * The process calling munmap. - * - * Arguments: - * address - the requested address - * length - the length of the memory segment */ probe vm.munmap = kernel.function("do_munmap") { address = $start length = $len } -/// -/// vm.brk -/// vm.brk -/// Fires when a brk is requested (resizing a heap). -/// -/// -/// Arguments: -/// address -/// The requested address. -/// -/// length -/// The length of the memory segment. -/// -/// -/// -/* probe vm.brk - * - * Fires when a brk is requested (resizing a heap). +/** + * probe vm.brk -Fires when a brk is requested (resizing a heap). + * @address - the requested address + * @length - the length of the memory segment * * Context: * The process calling brk. - * - * Arguments: - * address - the requested address - * length - the length of the memory segment */ probe vm.brk = kernel.function("do_brk") { address = $addr length = $len } -/// -/// vm.oom_kill -/// vm.oom_kill -/// Fires when a thread is targetted by the OOM killer. -/// -/// -/// Arguments: -/// task -/// The task being killed. -/// -/// -/// -/* probe vm.oom_kill - * - * Fires when a thread is targetted by the OOM killer. +/** + * probe vm.oom_kill - Fires when a thread is targetted by the OOM killer. + * @task: the task being killed * * Context: * The process that tried to consume more memory, and thus * triggered the OOM. (correct?) - * - * Arguments: - * task - the task being killed */ probe vm.oom_kill = kernel.function("__oom_kill_task") { task = $p } - -/// diff --git a/tapset/networking.stp b/tapset/networking.stp index decd62a..d6e9025 100644 --- a/tapset/networking.stp +++ b/tapset/networking.stp @@ -6,36 +6,17 @@ // Public License (GPL); either version 2, or (at your option) any // later version. -/// -/// Networking Tapset -/// -/// This family of probe points is used to probe the activities of -/// network device. -/// - %{ #include %} -/// -/// netdev.receive -/// netdev.receive -/// Fires when data arrives on network device. -/// -/// -/// Arguments: -/// dev_name -/// -/// The name of the device. e.g: eth0, ath1 -/// -/// -/// -/// length -/// -/// The length of the receiving buffer -/// -/// -/// +/** + * probe netdev.receive - Data recieved from network device. + * @dev_name: The name of the device. e.g: eth0, ath1. + * @length: The length of the receiving buffer. + * @protocol: Protocol of recieved packet. + * + */ /// protocol /// The possible values of protocol could be: /// Protocol Values @@ -82,39 +63,14 @@ probe netdev.receive truesize = $skb->truesize } -/// -/// netdev.transmit -/// netdev.transmit -/// Fires when the network device wants to transmit a buffer. -/// -/// -/// Arguments: -/// dev_name -/// -/// The name of the device. e.g: eth0, ath1 -/// -/// -/// -/// length -/// -/// The length of the transmit buffer -/// -/// -/// -/// protocol -/// -/// The protocol of this packet. -/// -/// -/// -/// truesize -/// -/// The size of the the data to be transmitted. -/// -/// -/// -/// -/// +/** + * probe netdev.transmit - Network device transmitting buffer + * @dev_name: The name of the device. e.g: eth0, ath1. + * @length: The length of the transmit buffer. + * @protocol: The protocol of this packet. + * @truesize: The size of the the data to be transmitted. + * + */ /* Queue a buffer for transmission to a network device */ probe netdev.transmit = kernel.function("dev_queue_xmit") @@ -124,5 +80,3 @@ probe netdev.transmit protocol = $skb->protocol truesize = $skb->truesize } - -/// diff --git a/tapset/timestamp.stp b/tapset/timestamp.stp index 4c8592a..29763cb 100644 --- a/tapset/timestamp.stp +++ b/tapset/timestamp.stp @@ -7,79 +7,57 @@ // Public License (GPL); either version 2, or (at your option) any // later version. -/// -/// Timestamp Functions -/// -/// Each timestamp function returns a value to indicate when -/// the function is executed. -/// Thus, these returned values can be used to indicate -/// when an event occurs, provide an ordering for events, or compute -/// the amount of time elapsed between to time stamps. -/// - %{ #include %} -/// -/// get_cycles:long() -/// get_cycles -/// -/// Return the processor cycle counter value, or 0 if unavailable. -/// -/// +/** + * sfunction get_cycles - Processor cycle count. + * + * Return the processor cycle counter value, or 0 if unavailable. + */ function get_cycles:long () %{ /* pure */ cycles_t c = get_cycles(); THIS->__retvalue = (int64_t) c; %} -/// -/// gettimeofday_ns:long () -/// gettimeofday_ns -/// -/// Return the number of nanoseconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_ns - Number of nanoseconds since UNIX epoch. + * + * Return the number of nanoseconds since the UNIX epoch. + */ function gettimeofday_ns:long () %{ /* pure */ /* NOTE: we can't use do_gettimeofday because we could be called from a * context where xtime_lock is already held. See bug #2525. */ THIS->__retvalue = _stp_gettimeofday_ns(); %} -/// -/// gettimeofday_us:long () -/// gettimeofday_us -/// -/// Return the number of microseconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_us - Number of microseconds since UNIX epoch. + * + * Return the number of microseconds since the UNIX epoch. + */ function gettimeofday_us:long () { return gettimeofday_ns() / 1000; } -/// -/// gettimeofday_ms:long () -/// gettimeofday_ms -/// -/// Return the number of milliseconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_ms - Number of milliseconds since UNIX epoch. + * + * Return the number of milliseconds since the UNIX epoch. + */ function gettimeofday_ms:long () { return gettimeofday_ns() / 1000000; } -/// -/// gettimeofday_s:long () -/// gettimeofday_s -/// -/// Return the number of seconds since the UNIX epoch. -/// -/// +/** + * sfunction gettimeofday_s - Number of seconds since UNIX epoch. + * + * Return the number of seconds since the UNIX epoch. + */ function gettimeofday_s:long () { return gettimeofday_ns() / 1000000000; } // likewise jiffies, monotonic_clock ... - -/// -- 1.5.6.5 --------------060802000209010300030008--