5 files changed, 691 insertions, 0 deletions

diff --git a/tools/perf/scripts/python/bin/compaction-times-record b/tools/perf/scripts/python/bin/compaction-times-record
new file mode 100644
index 000000000000..6edcd40e14e8
--- /dev/null
+++ b/tools/perf/scripts/python/bin/compaction-times-record
@@ -0,0 +1,2 @@
+#!/bin/bash
+perf record -e compaction:mm_compaction_begin -e compaction:mm_compaction_end -e compaction:mm_compaction_migratepages -e compaction:mm_compaction_isolate_migratepages -e compaction:mm_compaction_isolate_freepages $@
diff --git a/tools/perf/scripts/python/bin/compaction-times-report b/tools/perf/scripts/python/bin/compaction-times-report
new file mode 100644
index 000000000000..3dc13897cfde
--- /dev/null
+++ b/tools/perf/scripts/python/bin/compaction-times-report
@@ -0,0 +1,4 @@
+#!/bin/bash
+#description: display time taken by mm compaction
+#args: [-h] [-u] [-p|-pv] [-t | [-m] [-fs] [-ms]] [pid|pid-range|comm-regex]
+perf script -s "$PERF_EXEC_PATH"/scripts/python/compaction-times.py $@
diff --git a/tools/perf/scripts/python/call-graph-from-postgresql.py b/tools/perf/scripts/python/call-graph-from-postgresql.py
new file mode 100644
index 000000000000..e78fdc2a5a9d
--- /dev/null
+++ b/tools/perf/scripts/python/call-graph-from-postgresql.py
@@ -0,0 +1,327 @@
+#!/usr/bin/python2
+# call-graph-from-postgresql.py: create call-graph from postgresql database
+# Copyright (c) 2014, Intel Corporation.
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms and conditions of the GNU General Public License,
+# version 2, as published by the Free Software Foundation.
+#
+# This program is distributed in the hope 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.
+
+# To use this script you will need to have exported data using the
+# export-to-postgresql.py script.  Refer to that script for details.
+#
+# Following on from the example in the export-to-postgresql.py script, a
+# call-graph can be displayed for the pt_example database like this:
+#
+#       python tools/perf/scripts/python/call-graph-from-postgresql.py pt_example
+#
+# Note this script supports connecting to remote databases by setting hostname,
+# port, username, password, and dbname e.g.
+#
+#       python tools/perf/scripts/python/call-graph-from-postgresql.py "hostname=myhost username=myuser password=mypassword dbname=pt_example"
+#
+# The result is a GUI window with a tree representing a context-sensitive
+# call-graph.  Expanding a couple of levels of the tree and adjusting column
+# widths to suit will display something like:
+#
+#                                         Call Graph: pt_example
+# Call Path                          Object      Count   Time(ns)  Time(%)  Branch Count   Branch Count(%)
+# v- ls
+#     v- 2638:2638
+#         v- _start                  ld-2.19.so    1     10074071   100.0         211135            100.0
+#           |- unknown               unknown       1        13198     0.1              1              0.0
+#           >- _dl_start             ld-2.19.so    1      1400980    13.9          19637              9.3
+#           >- _d_linit_internal     ld-2.19.so    1       448152     4.4          11094              5.3
+#           v-__libc_start_main@plt  ls            1      8211741    81.5         180397             85.4
+#              >- _dl_fixup          ld-2.19.so    1         7607     0.1            108              0.1
+#              >- __cxa_atexit       libc-2.19.so  1        11737     0.1             10              0.0
+#              >- __libc_csu_init    ls            1        10354     0.1             10              0.0
+#              |- _setjmp            libc-2.19.so  1            0     0.0              4              0.0
+#              v- main               ls            1      8182043    99.6         180254             99.9
+#
+# Points to note:
+#       The top level is a command name (comm)
+#       The next level is a thread (pid:tid)
+#       Subsequent levels are functions
+#       'Count' is the number of calls
+#       'Time' is the elapsed time until the function returns
+#       Percentages are relative to the level above
+#       'Branch Count' is the total number of branches for that function and all
+#       functions that it calls
+
+import sys
+from PySide.QtCore import *
+from PySide.QtGui import *
+from PySide.QtSql import *
+from decimal import *
+
+class TreeItem():
+
+        def __init__(self, db, row, parent_item):
+                self.db = db
+                self.row = row
+                self.parent_item = parent_item
+                self.query_done = False;
+                self.child_count = 0
+                self.child_items = []
+                self.data = ["", "", "", "", "", "", ""]
+                self.comm_id = 0
+                self.thread_id = 0
+                self.call_path_id = 1
+                self.branch_count = 0
+                self.time = 0
+                if not parent_item:
+                        self.setUpRoot()
+
+        def setUpRoot(self):
+                self.query_done = True
+                query = QSqlQuery(self.db)
+                ret = query.exec_('SELECT id, comm FROM comms')
+                if not ret:
+                        raise Exception("Query failed: " + query.lastError().text())
+                while query.next():
+                        if not query.value(0):
+                                continue
+                        child_item = TreeItem(self.db, self.child_count, self)
+                        self.child_items.append(child_item)
+                        self.child_count += 1
+                        child_item.setUpLevel1(query.value(0), query.value(1))
+
+        def setUpLevel1(self, comm_id, comm):
+                self.query_done = True;
+                self.comm_id = comm_id
+                self.data[0] = comm
+                self.child_items = []
+                self.child_count = 0
+                query = QSqlQuery(self.db)
+                ret = query.exec_('SELECT thread_id, ( SELECT pid FROM threads WHERE id = thread_id ), ( SELECT tid FROM threads WHERE id = thread_id ) FROM comm_threads WHERE comm_id = ' + str(comm_id))
+                if not ret:
+                        raise Exception("Query failed: " + query.lastError().text())
+                while query.next():
+                        child_item = TreeItem(self.db, self.child_count, self)
+                        self.child_items.append(child_item)
+                        self.child_count += 1
+                        child_item.setUpLevel2(comm_id, query.value(0), query.value(1), query.value(2))
+
+        def setUpLevel2(self, comm_id, thread_id, pid, tid):
+                self.comm_id = comm_id
+                self.thread_id = thread_id
+                self.data[0] = str(pid) + ":" + str(tid)
+
+        def getChildItem(self, row):
+                return self.child_items[row]
+
+        def getParentItem(self):
+                return self.parent_item
+
+        def getRow(self):
+                return self.row
+
+        def timePercent(self, b):
+                if not self.time:
+                        return "0.0"
+                x = (b * Decimal(100)) / self.time
+                return str(x.quantize(Decimal('.1'), rounding=ROUND_HALF_UP))
+
+        def branchPercent(self, b):
+                if not self.branch_count:
+                        return "0.0"
+                x = (b * Decimal(100)) / self.branch_count
+                return str(x.quantize(Decimal('.1'), rounding=ROUND_HALF_UP))
+
+        def addChild(self, call_path_id, name, dso, count, time, branch_count):
+                child_item = TreeItem(self.db, self.child_count, self)
+                child_item.comm_id = self.comm_id
+                child_item.thread_id = self.thread_id
+                child_item.call_path_id = call_path_id
+                child_item.branch_count = branch_count
+                child_item.time = time
+                child_item.data[0] = name
+                if dso == "[kernel.kallsyms]":
+                        dso = "[kernel]"
+                child_item.data[1] = dso
+                child_item.data[2] = str(count)
+                child_item.data[3] = str(time)
+                child_item.data[4] = self.timePercent(time)
+                child_item.data[5] = str(branch_count)
+                child_item.data[6] = self.branchPercent(branch_count)
+                self.child_items.append(child_item)
+                self.child_count += 1
+
+        def selectCalls(self):
+                self.query_done = True;
+                query = QSqlQuery(self.db)
+                ret = query.exec_('SELECT id, call_path_id, branch_count, call_time, return_time, '
+                                  '( SELECT name FROM symbols WHERE id = ( SELECT symbol_id FROM call_paths WHERE id = call_path_id ) ), '
+                                  '( SELECT short_name FROM dsos WHERE id = ( SELECT dso_id FROM symbols WHERE id = ( SELECT symbol_id FROM call_paths WHERE id = call_path_id ) ) ), '
+                                  '( SELECT ip FROM call_paths where id = call_path_id ) '
+                                  'FROM calls WHERE parent_call_path_id = ' + str(self.call_path_id) + ' AND comm_id = ' + str(self.comm_id) + ' AND thread_id = ' + str(self.thread_id) +
+                                  'ORDER BY call_path_id')
+                if not ret:
+                        raise Exception("Query failed: " + query.lastError().text())
+                last_call_path_id = 0
+                name = ""
+                dso = ""
+                count = 0
+                branch_count = 0
+                total_branch_count = 0
+                time = 0
+                total_time = 0
+                while query.next():
+                        if query.value(1) == last_call_path_id:
+                                count += 1
+                                branch_count += query.value(2)
+                                time += query.value(4) - query.value(3)
+                        else:
+                                if count:
+                                        self.addChild(last_call_path_id, name, dso, count, time, branch_count)
+                                last_call_path_id = query.value(1)
+                                name = query.value(5)
+                                dso = query.value(6)
+                                count = 1
+                                total_branch_count += branch_count
+                                total_time += time
+                                branch_count = query.value(2)
+                                time = query.value(4) - query.value(3)
+                if count:
+                        self.addChild(last_call_path_id, name, dso, count, time, branch_count)
+                total_branch_count += branch_count
+                total_time += time
+                # Top level does not have time or branch count, so fix that here
+                if total_branch_count > self.branch_count:
+                        self.branch_count = total_branch_count
+                        if self.branch_count:
+                                for child_item in self.child_items:
+                                        child_item.data[6] = self.branchPercent(child_item.branch_count)
+                if total_time > self.time:
+                        self.time = total_time
+                        if self.time:
+                                for child_item in self.child_items:
+                                        child_item.data[4] = self.timePercent(child_item.time)
+
+        def childCount(self):
+                if not self.query_done:
+                        self.selectCalls()
+                return self.child_count
+
+        def columnCount(self):
+                return 7
+
+        def columnHeader(self, column):
+                headers = ["Call Path", "Object", "Count ", "Time (ns) ", "Time (%) ", "Branch Count ", "Branch Count (%) "]
+                return headers[column]
+
+        def getData(self, column):
+                return self.data[column]
+
+class TreeModel(QAbstractItemModel):
+
+        def __init__(self, db, parent=None):
+                super(TreeModel, self).__init__(parent)
+                self.db = db
+                self.root = TreeItem(db, 0, None)
+
+        def columnCount(self, parent):
+                return self.root.columnCount()
+
+        def rowCount(self, parent):
+                if parent.isValid():
+                        parent_item = parent.internalPointer()
+                else:
+                        parent_item = self.root
+                return parent_item.childCount()
+
+        def headerData(self, section, orientation, role):
+                if role == Qt.TextAlignmentRole:
+                        if section > 1:
+                                return Qt.AlignRight
+                if role != Qt.DisplayRole:
+                        return None
+                if orientation != Qt.Horizontal:
+                        return None
+                return self.root.columnHeader(section)
+
+        def parent(self, child):
+                child_item = child.internalPointer()
+                if child_item is self.root:
+                        return QModelIndex()
+                parent_item = child_item.getParentItem()
+                return self.createIndex(parent_item.getRow(), 0, parent_item)
+
+        def index(self, row, column, parent):
+                if parent.isValid():
+                        parent_item = parent.internalPointer()
+                else:
+                        parent_item = self.root
+                child_item = parent_item.getChildItem(row)
+                return self.createIndex(row, column, child_item)
+
+        def data(self, index, role):
+                if role == Qt.TextAlignmentRole:
+                        if index.column() > 1:
+                                return Qt.AlignRight
+                if role != Qt.DisplayRole:
+                        return None
+                index_item = index.internalPointer()
+                return index_item.getData(index.column())
+
+class MainWindow(QMainWindow):
+
+        def __init__(self, db, dbname, parent=None):
+                super(MainWindow, self).__init__(parent)
+
+                self.setObjectName("MainWindow")
+                self.setWindowTitle("Call Graph: " + dbname)
+                self.move(100, 100)
+                self.resize(800, 600)
+                style = self.style()
+                icon = style.standardIcon(QStyle.SP_MessageBoxInformation)
+                self.setWindowIcon(icon);
+
+                self.model = TreeModel(db)
+
+                self.view = QTreeView()
+                self.view.setModel(self.model)
+
+                self.setCentralWidget(self.view)
+
+if __name__ == '__main__':
+        if (len(sys.argv) < 2):
+                print >> sys.stderr, "Usage is: call-graph-from-postgresql.py <database name>"
+                raise Exception("Too few arguments")
+
+        dbname = sys.argv[1]
+
+        db = QSqlDatabase.addDatabase('QPSQL')
+
+        opts = dbname.split()
+        for opt in opts:
+                if '=' in opt:
+                        opt = opt.split('=')
+                        if opt[0] == 'hostname':
+                                db.setHostName(opt[1])
+                        elif opt[0] == 'port':
+                                db.setPort(int(opt[1]))
+                        elif opt[0] == 'username':
+                                db.setUserName(opt[1])
+                        elif opt[0] == 'password':
+                                db.setPassword(opt[1])
+                        elif opt[0] == 'dbname':
+                                dbname = opt[1]
+                else:
+                        dbname = opt
+
+        db.setDatabaseName(dbname)
+        if not db.open():
+                raise Exception("Failed to open database " + dbname + " error: " + db.lastError().text())
+
+        app = QApplication(sys.argv)
+        window = MainWindow(db, dbname)
+        window.show()
+        err = app.exec_()
+        db.close()
+        sys.exit(err)
diff --git a/tools/perf/scripts/python/compaction-times.py b/tools/perf/scripts/python/compaction-times.py
new file mode 100644
index 000000000000..239cb0568ec3
--- /dev/null
+++ b/tools/perf/scripts/python/compaction-times.py
@@ -0,0 +1,311 @@
+# report time spent in compaction
+# Licensed under the terms of the GNU GPL License version 2
+
+# testing:
+# 'echo 1 > /proc/sys/vm/compact_memory' to force compaction of all zones
+
+import os
+import sys
+import re
+
+import signal
+signal.signal(signal.SIGPIPE, signal.SIG_DFL)
+
+usage = "usage: perf script report compaction-times.py -- [-h] [-u] [-p|-pv] [-t | [-m] [-fs] [-ms]] [pid|pid-range|comm-regex]\n"
+
+class popt:
+        DISP_DFL = 0
+        DISP_PROC = 1
+        DISP_PROC_VERBOSE=2
+
+class topt:
+        DISP_TIME = 0
+        DISP_MIG = 1
+        DISP_ISOLFREE = 2
+        DISP_ISOLMIG = 4
+        DISP_ALL = 7
+
+class comm_filter:
+        def __init__(self, re):
+                self.re = re
+
+        def filter(self, pid, comm):
+                m = self.re.search(comm)
+                return m == None or m.group() == ""
+
+class pid_filter:
+        def __init__(self, low, high):
+                self.low = (0 if low == "" else int(low))
+                self.high = (0 if high == "" else int(high))
+
+        def filter(self, pid, comm):
+                return not (pid >= self.low and (self.high == 0 or pid <= self.high))
+
+def set_type(t):
+        global opt_disp
+        opt_disp = (t if opt_disp == topt.DISP_ALL else opt_disp|t)
+
+def ns(sec, nsec):
+        return (sec * 1000000000) + nsec
+
+def time(ns):
+        return "%dns" % ns if opt_ns else "%dus" % (round(ns, -3) / 1000)
+
+class pair:
+        def __init__(self, aval, bval, alabel = None, blabel = None):
+                self.alabel = alabel
+                self.blabel = blabel
+                self.aval = aval
+                self.bval = bval
+
+        def __add__(self, rhs):
+                self.aval += rhs.aval
+                self.bval += rhs.bval
+                return self
+
+        def __str__(self):
+                return "%s=%d %s=%d" % (self.alabel, self.aval, self.blabel, self.bval)
+
+class cnode:
+        def __init__(self, ns):
+                self.ns = ns
+                self.migrated = pair(0, 0, "moved", "failed")
+                self.fscan = pair(0,0, "scanned", "isolated")
+                self.mscan = pair(0,0, "scanned", "isolated")
+
+        def __add__(self, rhs):
+                self.ns += rhs.ns
+                self.migrated += rhs.migrated
+                self.fscan += rhs.fscan
+                self.mscan += rhs.mscan
+                return self
+
+        def __str__(self):
+                prev = 0
+                s = "%s " % time(self.ns)
+                if (opt_disp & topt.DISP_MIG):
+                        s += "migration: %s" % self.migrated
+                        prev = 1
+                if (opt_disp & topt.DISP_ISOLFREE):
+                        s += "%sfree_scanner: %s" % (" " if prev else "", self.fscan)
+                        prev = 1
+                if (opt_disp & topt.DISP_ISOLMIG):
+                        s += "%smigration_scanner: %s" % (" " if prev else "", self.mscan)
+                return s
+
+        def complete(self, secs, nsecs):
+                self.ns = ns(secs, nsecs) - self.ns
+
+        def increment(self, migrated, fscan, mscan):
+                if (migrated != None):
+                        self.migrated += migrated
+                if (fscan != None):
+                        self.fscan += fscan
+                if (mscan != None):
+                        self.mscan += mscan
+
+
+class chead:
+        heads = {}
+        val = cnode(0);
+        fobj = None
+
+        @classmethod
+        def add_filter(cls, filter):
+                cls.fobj = filter
+
+        @classmethod
+        def create_pending(cls, pid, comm, start_secs, start_nsecs):
+                filtered = 0
+                try:
+                        head = cls.heads[pid]
+                        filtered = head.is_filtered()
+                except KeyError:
+                        if cls.fobj != None:
+                                filtered = cls.fobj.filter(pid, comm)
+                        head = cls.heads[pid] = chead(comm, pid, filtered)
+
+                if not filtered:
+                        head.mark_pending(start_secs, start_nsecs)
+
+        @classmethod
+        def increment_pending(cls, pid, migrated, fscan, mscan):
+                head = cls.heads[pid]
+                if not head.is_filtered():
+                        if head.is_pending():
+                                head.do_increment(migrated, fscan, mscan)
+                        else:
+                                sys.stderr.write("missing start compaction event for pid %d\n" % pid)
+
+        @classmethod
+        def complete_pending(cls, pid, secs, nsecs):
+                head = cls.heads[pid]
+                if not head.is_filtered():
+                        if head.is_pending():
+                                head.make_complete(secs, nsecs)
+                        else:
+                                sys.stderr.write("missing start compaction event for pid %d\n" % pid)
+
+        @classmethod
+        def gen(cls):
+                if opt_proc != popt.DISP_DFL:
+                        for i in cls.heads:
+                                yield cls.heads[i]
+
+        @classmethod
+        def str(cls):
+                return cls.val
+
+        def __init__(self, comm, pid, filtered):
+                self.comm = comm
+                self.pid = pid
+                self.val = cnode(0)
+                self.pending = None
+                self.filtered = filtered
+                self.list = []
+
+        def __add__(self, rhs):
+                self.ns += rhs.ns
+                self.val += rhs.val
+                return self
+
+        def mark_pending(self, secs, nsecs):
+                self.pending = cnode(ns(secs, nsecs))
+
+        def do_increment(self, migrated, fscan, mscan):
+                self.pending.increment(migrated, fscan, mscan)
+
+        def make_complete(self, secs, nsecs):
+                self.pending.complete(secs, nsecs)
+                chead.val += self.pending
+
+                if opt_proc != popt.DISP_DFL:
+                        self.val += self.pending
+
+                        if opt_proc == popt.DISP_PROC_VERBOSE:
+                                self.list.append(self.pending)
+                self.pending = None
+
+        def enumerate(self):
+                if opt_proc == popt.DISP_PROC_VERBOSE and not self.is_filtered():
+                        for i, pelem in enumerate(self.list):
+                                sys.stdout.write("%d[%s].%d: %s\n" % (self.pid, self.comm, i+1, pelem))
+
+        def is_pending(self):
+                return self.pending != None
+
+        def is_filtered(self):
+                return self.filtered
+
+        def display(self):
+                if not self.is_filtered():
+                        sys.stdout.write("%d[%s]: %s\n" % (self.pid, self.comm, self.val))
+
+
+def trace_end():
+        sys.stdout.write("total: %s\n" % chead.str())
+        for i in chead.gen():
+                i.display(),
+                i.enumerate()
+
+def compaction__mm_compaction_migratepages(event_name, context, common_cpu,
+        common_secs, common_nsecs, common_pid, common_comm,
+        common_callchain, nr_migrated, nr_failed):
+
+        chead.increment_pending(common_pid,
+                pair(nr_migrated, nr_failed), None, None)
+
+def compaction__mm_compaction_isolate_freepages(event_name, context, common_cpu,
+        common_secs, common_nsecs, common_pid, common_comm,
+        common_callchain, start_pfn, end_pfn, nr_scanned, nr_taken):
+
+        chead.increment_pending(common_pid,
+                None, pair(nr_scanned, nr_taken), None)
+
+def compaction__mm_compaction_isolate_migratepages(event_name, context, common_cpu,
+        common_secs, common_nsecs, common_pid, common_comm,
+        common_callchain, start_pfn, end_pfn, nr_scanned, nr_taken):
+
+        chead.increment_pending(common_pid,
+                None, None, pair(nr_scanned, nr_taken))
+
+def compaction__mm_compaction_end(event_name, context, common_cpu,
+        common_secs, common_nsecs, common_pid, common_comm,
+        common_callchain, zone_start, migrate_start, free_start, zone_end,
+        sync, status):
+
+        chead.complete_pending(common_pid, common_secs, common_nsecs)
+
+def compaction__mm_compaction_begin(event_name, context, common_cpu,
+        common_secs, common_nsecs, common_pid, common_comm,
+        common_callchain, zone_start, migrate_start, free_start, zone_end,
+        sync):
+
+        chead.create_pending(common_pid, common_comm, common_secs, common_nsecs)
+
+def pr_help():
+        global usage
+
+        sys.stdout.write(usage)
+        sys.stdout.write("\n")
+        sys.stdout.write("-h    display this help\n")
+        sys.stdout.write("-p    display by process\n")
+        sys.stdout.write("-pv   display by process (verbose)\n")
+        sys.stdout.write("-t    display stall times only\n")
+        sys.stdout.write("-m    display stats for migration\n")
+        sys.stdout.write("-fs   display stats for free scanner\n")
+        sys.stdout.write("-ms   display stats for migration scanner\n")
+        sys.stdout.write("-u    display results in microseconds (default nanoseconds)\n")
+
+
+comm_re = None
+pid_re = None
+pid_regex = "^(\d*)-(\d*)$|^(\d*)$"
+
+opt_proc = popt.DISP_DFL
+opt_disp = topt.DISP_ALL
+
+opt_ns = True
+
+argc = len(sys.argv) - 1
+if argc >= 1:
+        pid_re = re.compile(pid_regex)
+
+        for i, opt in enumerate(sys.argv[1:]):
+                if opt[0] == "-":
+                        if opt == "-h":
+                                pr_help()
+                                exit(0);
+                        elif opt == "-p":
+                                opt_proc = popt.DISP_PROC
+                        elif opt == "-pv":
+                                opt_proc = popt.DISP_PROC_VERBOSE
+                        elif opt == '-u':
+                                opt_ns = False
+                        elif opt == "-t":
+                                set_type(topt.DISP_TIME)
+                        elif opt == "-m":
+                                set_type(topt.DISP_MIG)
+                        elif opt == "-fs":
+                                set_type(topt.DISP_ISOLFREE)
+                        elif opt == "-ms":
+                                set_type(topt.DISP_ISOLMIG)
+                        else:
+                                sys.exit(usage)
+
+                elif i == argc - 1:
+                        m = pid_re.search(opt)
+                        if m != None and m.group() != "":
+                                if m.group(3) != None:
+                                        f = pid_filter(m.group(3), m.group(3))
+                                else:
+                                        f = pid_filter(m.group(1), m.group(2))
+                        else:
+                                try:
+                                        comm_re=re.compile(opt)
+                                except:
+                                        sys.stderr.write("invalid regex '%s'" % opt)
+                                        sys.exit(usage)
+                                f = comm_filter(comm_re)
+
+                        chead.add_filter(f)
diff --git a/tools/perf/scripts/python/export-to-postgresql.py b/tools/perf/scripts/python/export-to-postgresql.py
index 4cdafd880074..84a32037a80f 100644
--- a/tools/perf/scripts/python/export-to-postgresql.py
+++ b/tools/perf/scripts/python/export-to-postgresql.py
@@ -15,6 +15,53 @@ import sys
 import struct
 import datetime
 
+# To use this script you will need to have installed package python-pyside which
+# provides LGPL-licensed Python bindings for Qt.  You will also need the package
+# libqt4-sql-psql for Qt postgresql support.
+#
+# The script assumes postgresql is running on the local machine and that the
+# user has postgresql permissions to create databases. Examples of installing
+# postgresql and adding such a user are:
+#
+# fedora:
+#
+#       $ sudo yum install postgresql postgresql-server python-pyside qt-postgresql
+#       $ sudo su - postgres -c initdb
+#       $ sudo service postgresql start
+#       $ sudo su - postgres
+#       $ createuser <your user id here>
+#       Shall the new role be a superuser? (y/n) y
+#
+# ubuntu:
+#
+#       $ sudo apt-get install postgresql
+#       $ sudo su - postgres
+#       $ createuser <your user id here>
+#       Shall the new role be a superuser? (y/n) y
+#
+# An example of using this script with Intel PT:
+#
+#       $ perf record -e intel_pt//u ls
+#       $ perf script -s ~/libexec/perf-core/scripts/python/export-to-postgresql.py pt_example branches calls
+#       2015-05-29 12:49:23.464364 Creating database...
+#       2015-05-29 12:49:26.281717 Writing to intermediate files...
+#       2015-05-29 12:49:27.190383 Copying to database...
+#       2015-05-29 12:49:28.140451 Removing intermediate files...
+#       2015-05-29 12:49:28.147451 Adding primary keys
+#       2015-05-29 12:49:28.655683 Adding foreign keys
+#       2015-05-29 12:49:29.365350 Done
+#
+# To browse the database, psql can be used e.g.
+#
+#       $ psql pt_example
+#       pt_example=# select * from samples_view where id < 100;
+#       pt_example=# \d+
+#       pt_example=# \d+ samples_view
+#       pt_example=# \q
+#
+# An example of using the database is provided by the script
+# call-graph-from-postgresql.py.  Refer to that script for details.
+
 from PySide.QtSql import *
 
 # Need to access PostgreSQL C library directly to use COPY FROM STDIN