1 files changed, 515 insertions, 0 deletions
diff --git a/test/py/multiplexed_log.py b/test/py/multiplexed_log.py
new file mode 100644
index 0000000000..48f2b51de1
--- /dev/null
+++ b/test/py/multiplexed_log.py
@@ -0,0 +1,515 @@
+# Copyright (c) 2015 Stephen Warren
+# Copyright (c) 2015-2016, NVIDIA CORPORATION. All rights reserved.
+#
+# SPDX-License-Identifier: GPL-2.0
+
+# Generate an HTML-formatted log file containing multiple streams of data,
+# each represented in a well-delineated/-structured fashion.
+
+import cgi
+import os.path
+import shutil
+import subprocess
+
+mod_dir = os.path.dirname(os.path.abspath(__file__))
+
+class LogfileStream(object):
+    '''A file-like object used to write a single logical stream of data into
+    a multiplexed log file. Objects of this type should be created by factory
+    functions in the Logfile class rather than directly.'''
+
+    def __init__(self, logfile, name, chained_file):
+        '''Initialize a new object.
+
+        Args:
+            logfile: The Logfile object to log to.
+            name: The name of this log stream.
+            chained_file: The file-like object to which all stream data should be
+            logged to in addition to logfile. Can be None.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.logfile = logfile
+        self.name = name
+        self.chained_file = chained_file
+
+    def close(self):
+        '''Dummy function so that this class is "file-like".
+
+        Args:
+            None.
+
+        Returns:
+            Nothing.
+        '''
+
+        pass
+
+    def write(self, data, implicit=False):
+        '''Write data to the log stream.
+
+        Args:
+            data: The data to write tot he file.
+            implicit: Boolean indicating whether data actually appeared in the
+                stream, or was implicitly generated. A valid use-case is to
+                repeat a shell prompt at the start of each separate log
+                section, which makes the log sections more readable in
+                isolation.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.logfile.write(self, data, implicit)
+        if self.chained_file:
+            self.chained_file.write(data)
+
+    def flush(self):
+        '''Flush the log stream, to ensure correct log interleaving.
+
+        Args:
+            None.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.logfile.flush()
+        if self.chained_file:
+            self.chained_file.flush()
+
+class RunAndLog(object):
+    '''A utility object used to execute sub-processes and log their output to
+    a multiplexed log file. Objects of this type should be created by factory
+    functions in the Logfile class rather than directly.'''
+
+    def __init__(self, logfile, name, chained_file):
+        '''Initialize a new object.
+
+        Args:
+            logfile: The Logfile object to log to.
+            name: The name of this log stream or sub-process.
+            chained_file: The file-like object to which all stream data should
+                be logged to in addition to logfile. Can be None.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.logfile = logfile
+        self.name = name
+        self.chained_file = chained_file
+
+    def close(self):
+        '''Clean up any resources managed by this object.'''
+        pass
+
+    def run(self, cmd, cwd=None):
+        '''Run a command as a sub-process, and log the results.
+
+        Args:
+            cmd: The command to execute.
+            cwd: The directory to run the command in. Can be None to use the
+                current directory.
+
+        Returns:
+            Nothing.
+        '''
+
+        msg = "+" + " ".join(cmd) + "\n"
+        if self.chained_file:
+            self.chained_file.write(msg)
+        self.logfile.write(self, msg)
+
+        try:
+            p = subprocess.Popen(cmd, cwd=cwd,
+                stdin=None, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+            (stdout, stderr) = p.communicate()
+            output = ''
+            if stdout:
+                if stderr:
+                    output += 'stdout:\n'
+                output += stdout
+            if stderr:
+                if stdout:
+                    output += 'stderr:\n'
+                output += stderr
+            exit_status = p.returncode
+            exception = None
+        except subprocess.CalledProcessError as cpe:
+            output = cpe.output
+            exit_status = cpe.returncode
+            exception = cpe
+        except Exception as e:
+            output = ''
+            exit_status = 0
+            exception = e
+        if output and not output.endswith('\n'):
+            output += '\n'
+        if exit_status and not exception:
+            exception = Exception('Exit code: ' + str(exit_status))
+        if exception:
+            output += str(exception) + '\n'
+        self.logfile.write(self, output)
+        if self.chained_file:
+            self.chained_file.write(output)
+        if exception:
+            raise exception
+
+class SectionCtxMgr(object):
+    '''A context manager for Python's "with" statement, which allows a certain
+    portion of test code to be logged to a separate section of the log file.
+    Objects of this type should be created by factory functions in the Logfile
+    class rather than directly.'''
+
+    def __init__(self, log, marker):
+        '''Initialize a new object.
+
+        Args:
+            log: The Logfile object to log to.
+            marker: The name of the nested log section.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.log = log
+        self.marker = marker
+
+    def __enter__(self):
+        self.log.start_section(self.marker)
+
+    def __exit__(self, extype, value, traceback):
+        self.log.end_section(self.marker)
+
+class Logfile(object):
+    '''Generates an HTML-formatted log file containing multiple streams of
+    data, each represented in a well-delineated/-structured fashion.'''
+
+    def __init__(self, fn):
+        '''Initialize a new object.
+
+        Args:
+            fn: The filename to write to.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.f = open(fn, "wt")
+        self.last_stream = None
+        self.blocks = []
+        self.cur_evt = 1
+        shutil.copy(mod_dir + "/multiplexed_log.css", os.path.dirname(fn))
+        self.f.write("""\
+<html>
+<head>
+<link rel="stylesheet" type="text/css" href="multiplexed_log.css">
+</head>
+<body>
+<tt>
+""")
+
+    def close(self):
+        '''Close the log file.
+
+        After calling this function, no more data may be written to the log.
+
+        Args:
+            None.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.f.write("""\
+</tt>
+</body>
+</html>
+""")
+        self.f.close()
+
+    # The set of characters that should be represented as hexadecimal codes in
+    # the log file.
+    _nonprint = ("%" + "".join(chr(c) for c in range(0, 32) if c not in (9, 10)) +
+                 "".join(chr(c) for c in range(127, 256)))
+
+    def _escape(self, data):
+        '''Render data format suitable for inclusion in an HTML document.
+
+        This includes HTML-escaping certain characters, and translating
+        control characters to a hexadecimal representation.
+
+        Args:
+            data: The raw string data to be escaped.
+
+        Returns:
+            An escaped version of the data.
+        '''
+
+        data = data.replace(chr(13), "")
+        data = "".join((c in self._nonprint) and ("%%%02x" % ord(c)) or
+                       c for c in data)
+        data = cgi.escape(data)
+        return data
+
+    def _terminate_stream(self):
+        '''Write HTML to the log file to terminate the current stream's data.
+
+        Args:
+            None.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.cur_evt += 1
+        if not self.last_stream:
+            return
+        self.f.write("</pre>\n")
+        self.f.write("<div class=\"stream-trailer\" id=\"" +
+                     self.last_stream.name + "\">End stream: " +
+                     self.last_stream.name + "</div>\n")
+        self.f.write("</div>\n")
+        self.last_stream = None
+
+    def _note(self, note_type, msg):
+        '''Write a note or one-off message to the log file.
+
+        Args:
+            note_type: The type of note. This must be a value supported by the
+                accompanying multiplexed_log.css.
+            msg: The note/message to log.
+
+        Returns:
+            Nothing.
+        '''
+
+        self._terminate_stream()
+        self.f.write("<div class=\"" + note_type + "\">\n<pre>")
+        self.f.write(self._escape(msg))
+        self.f.write("\n</pre></div>\n")
+
+    def start_section(self, marker):
+        '''Begin a new nested section in the log file.
+
+        Args:
+            marker: The name of the section that is starting.
+
+        Returns:
+            Nothing.
+        '''
+
+        self._terminate_stream()
+        self.blocks.append(marker)
+        blk_path = "/".join(self.blocks)
+        self.f.write("<div class=\"section\" id=\"" + blk_path + "\">\n")
+        self.f.write("<div class=\"section-header\" id=\"" + blk_path +
+                     "\">Section: " + blk_path + "</div>\n")
+
+    def end_section(self, marker):
+        '''Terminate the current nested section in the log file.
+
+        This function validates proper nesting of start_section() and
+        end_section() calls. If a mismatch is found, an exception is raised.
+
+        Args:
+            marker: The name of the section that is ending.
+
+        Returns:
+            Nothing.
+        '''
+
+        if (not self.blocks) or (marker != self.blocks[-1]):
+            raise Exception("Block nesting mismatch: \"%s\" \"%s\"" %
+                            (marker, "/".join(self.blocks)))
+        self._terminate_stream()
+        blk_path = "/".join(self.blocks)
+        self.f.write("<div class=\"section-trailer\" id=\"section-trailer-" +
+                     blk_path + "\">End section: " + blk_path + "</div>\n")
+        self.f.write("</div>\n")
+        self.blocks.pop()
+
+    def section(self, marker):
+        '''Create a temporary section in the log file.
+
+        This function creates a context manager for Python's "with" statement,
+        which allows a certain portion of test code to be logged to a separate
+        section of the log file.
+
+        Usage:
+            with log.section("somename"):
+                some test code
+
+        Args:
+            marker: The name of the nested section.
+
+        Returns:
+            A context manager object.
+        '''
+
+        return SectionCtxMgr(self, marker)
+
+    def error(self, msg):
+        '''Write an error note to the log file.
+
+        Args:
+            msg: A message describing the error.
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("error", msg)
+
+    def warning(self, msg):
+        '''Write an warning note to the log file.
+
+        Args:
+            msg: A message describing the warning.
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("warning", msg)
+
+    def info(self, msg):
+        '''Write an informational note to the log file.
+
+        Args:
+            msg: An informational message.
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("info", msg)
+
+    def action(self, msg):
+        '''Write an action note to the log file.
+
+        Args:
+            msg: A message describing the action that is being logged.
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("action", msg)
+
+    def status_pass(self, msg):
+        '''Write a note to the log file describing test(s) which passed.
+
+        Args:
+            msg: A message describing passed test(s).
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("status-pass", msg)
+
+    def status_skipped(self, msg):
+        '''Write a note to the log file describing skipped test(s).
+
+        Args:
+            msg: A message describing passed test(s).
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("status-skipped", msg)
+
+    def status_fail(self, msg):
+        '''Write a note to the log file describing failed test(s).
+
+        Args:
+            msg: A message describing passed test(s).
+
+        Returns:
+            Nothing.
+        '''
+
+        self._note("status-fail", msg)
+
+    def get_stream(self, name, chained_file=None):
+        '''Create an object to log a single stream's data into the log file.
+
+        This creates a "file-like" object that can be written to in order to
+        write a single stream's data to the log file. The implementation will
+        handle any required interleaving of data (from multiple streams) in
+        the log, in a way that makes it obvious which stream each bit of data
+        came from.
+
+        Args:
+            name: The name of the stream.
+            chained_file: The file-like object to which all stream data should
+                be logged to in addition to this log. Can be None.
+
+        Returns:
+            A file-like object.
+        '''
+
+        return LogfileStream(self, name, chained_file)
+
+    def get_runner(self, name, chained_file=None):
+        '''Create an object that executes processes and logs their output.
+
+        Args:
+            name: The name of this sub-process.
+            chained_file: The file-like object to which all stream data should
+                be logged to in addition to logfile. Can be None.
+
+        Returns:
+            A RunAndLog object.
+        '''
+
+        return RunAndLog(self, name, chained_file)
+
+    def write(self, stream, data, implicit=False):
+        '''Write stream data into the log file.
+
+        This function should only be used by instances of LogfileStream or
+        RunAndLog.
+
+        Args:
+            stream: The stream whose data is being logged.
+            data: The data to log.
+            implicit: Boolean indicating whether data actually appeared in the
+                stream, or was implicitly generated. A valid use-case is to
+                repeat a shell prompt at the start of each separate log
+                section, which makes the log sections more readable in
+                isolation.
+
+        Returns:
+            Nothing.
+        '''
+
+        if stream != self.last_stream:
+            self._terminate_stream()
+            self.f.write("<div class=\"stream\" id=\"%s\">\n" % stream.name)
+            self.f.write("<div class=\"stream-header\" id=\"" + stream.name +
+                         "\">Stream: " + stream.name + "</div>\n")
+            self.f.write("<pre>")
+        if implicit:
+            self.f.write("<span class=\"implicit\">")
+        self.f.write(self._escape(data))
+        if implicit:
+            self.f.write("</span>")
+        self.last_stream = stream
+
+    def flush(self):
+        '''Flush the log stream, to ensure correct log interleaving.
+
+        Args:
+            None.
+
+        Returns:
+            Nothing.
+        '''
+
+        self.f.flush()