config: Add configs scripts used in Learning gem5

Added a new directory in configs (learning_gem5) to hold the scripts that are
used in the book. See http://lowepower.com/jason/learning_gem5/ for a working
copy. For now, only the scripts in Part 1: Getting started with gem5
have been added. A separate patch adds tests for these scripts.

Committed by: Nilay Vaish <nilay@cs.wisc.edu>

5 files changed, 487 insertions, 0 deletions

diff --git a/configs/common/SimpleOpts.py b/configs/common/SimpleOpts.py
new file mode 100644
index 000000000..e2f122eab
--- /dev/null
+++ b/configs/common/SimpleOpts.py
@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2015 Jason Power
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met: redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer;
+# redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution;
+# neither the name of the copyright holders nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Authors: Jason Power
+
+""" Options wrapper for simple gem5 configuration scripts
+
+This module wraps the optparse class so that we can register options
+from each class instead of only from the configuration script.
+
+"""
+
+# Module-level variable to track if we've called the parse_args function yet
+called_parse_args = False
+
+# For fatal
+import m5
+
+# import the options parser
+from optparse import OptionParser
+
+# add the options we want to be able to control from the command line
+parser = OptionParser()
+
+def add_option(*args, **kwargs):
+    """Call "add_option" to the global options parser
+    """
+
+    if (parser.has_option(args[0]) or
+            (len(args) > 1 and parser.has_option(args[1])) ):
+        m5.fatal("Duplicate option: %s" % str(args))
+
+    if called_parse_args:
+        m5.fatal("Can't add an option after calling SimpleOpts.parse_args")
+
+    parser.add_option(*args, **kwargs)
+
+def parse_args():
+    global called_parse_args
+    called_parse_args = True
+
+    return parser.parse_args()
+
+def set_usage(*args, **kwargs):
+    parser.set_usage(*args, **kwargs)
+
+def print_help(*args, **kwargs):
+    parser.print_help(*args, **kwargs)
+
diff --git a/configs/learning_gem5/README b/configs/learning_gem5/README
new file mode 100644
index 000000000..ae7d62aab
--- /dev/null
+++ b/configs/learning_gem5/README
@@ -0,0 +1,29 @@
+
+Learning_gem README
+-------------------
+This directory contains the configuration scripts used in the "Learning gem5"
+book. The scripts contained in these directories are for educational purposes
+only and should not be used for architectural research as-is.
+
+"Learning gem5" is currently in early development stages. A pre-alpha working
+version of the book can be found at the following URL.
+
+http://lowepower.com/jason/learning_gem5/
+
+This directory is broken into one subdirectory per part of the book.
+
+Goals of these scripts
+~~~~~~~~~~~~~~~~~~~~~~
+These scripts are not necessarily useful outside the scope of the learning
+gem5 book. The goal is to include the learning gem5 scripts, following the
+book as closely as possible, so that the regression tester will catch any
+changes that affect the book.
+
+For general users, these are *not* good scripts to use for running complex
+architectural experiments. These scripts *are* a good starting point example
+of how to write your own scripts for experiments.
+
+Feedback
+~~~~~~~~
+Send mail to power.jg@gmail.com to provide feedback.
+
diff --git a/configs/learning_gem5/part1/caches.py b/configs/learning_gem5/part1/caches.py
new file mode 100644
index 000000000..fbdd1bf3c
--- /dev/null
+++ b/configs/learning_gem5/part1/caches.py
@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2015 Jason Power
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met: redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer;
+# redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution;
+# neither the name of the copyright holders nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Authors: Jason Power
+
+""" Caches with options for a simple gem5 configuration script
+
+This file contains L1 I/D and L2 caches to be used in the simple
+gem5 configuration script. It uses the SimpleOpts wrapper to set up command
+line options from each individual class.
+"""
+
+from m5.objects import Cache
+
+import SimpleOpts
+
+# Some specific options for caches
+# For all options see src/mem/cache/BaseCache.py
+
+class L1Cache(Cache):
+    """Simple L1 Cache with default values"""
+
+    assoc = 2
+    hit_latency = 2
+    response_latency = 2
+    mshrs = 4
+    tgts_per_mshr = 20
+
+    def __init__(self, options=None):
+        super(L1Cache, self).__init__()
+        pass
+
+    def connectBus(self, bus):
+        """Connect this cache to a memory-side bus"""
+        self.mem_side = bus.slave
+
+    def connectCPU(self, cpu):
+        """Connect this cache's port to a CPU-side port
+           This must be defined in a subclass"""
+        raise NotImplementedError
+
+class L1ICache(L1Cache):
+    """Simple L1 instruction cache with default values"""
+
+    # Set the default size
+    size = '16kB'
+
+    SimpleOpts.add_option('--l1i_size',
+                          help="L1 instruction cache size. Default: %s" % size)
+
+    def __init__(self, opts=None):
+        super(L1ICache, self).__init__(opts)
+        if not opts or not opts.l1i_size:
+            return
+        self.size = opts.l1i_size
+
+    def connectCPU(self, cpu):
+        """Connect this cache's port to a CPU icache port"""
+        self.cpu_side = cpu.icache_port
+
+class L1DCache(L1Cache):
+    """Simple L1 data cache with default values"""
+
+    # Set the default size
+    size = '64kB'
+
+    SimpleOpts.add_option('--l1d_size',
+                          help="L1 data cache size. Default: %s" % size)
+
+    def __init__(self, opts=None):
+        super(L1DCache, self).__init__(opts)
+        if not opts or not opts.l1d_size:
+            return
+        self.size = opts.l1d_size
+
+    def connectCPU(self, cpu):
+        """Connect this cache's port to a CPU dcache port"""
+        self.cpu_side = cpu.dcache_port
+
+class L2Cache(Cache):
+    """Simple L2 Cache with default values"""
+
+    # Default parameters
+    size = '256kB'
+    assoc = 8
+    hit_latency = 20
+    response_latency = 20
+    mshrs = 20
+    tgts_per_mshr = 12
+
+    SimpleOpts.add_option('--l2_size', help="L2 cache size. Default: %s" % size)
+
+    def __init__(self, opts=None):
+        super(L2Cache, self).__init__()
+        if not opts or not opts.l2_size:
+            return
+        self.size = opts.l2_size
+
+    def connectCPUSideBus(self, bus):
+        self.cpu_side = bus.master
+
+    def connectMemSideBus(self, bus):
+        self.mem_side = bus.slave
diff --git a/configs/learning_gem5/part1/simple.py b/configs/learning_gem5/part1/simple.py
new file mode 100644
index 000000000..8e3fed658
--- /dev/null
+++ b/configs/learning_gem5/part1/simple.py
@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2015 Jason Power
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met: redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer;
+# redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution;
+# neither the name of the copyright holders nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Authors: Jason Power
+
+""" This file creates a barebones system and executes 'hello', a simple Hello
+World application.
+See Part 1, Chapter 2: Creating a simple configuration script in the
+learning_gem5 book for more information about this script.
+
+IMPORTANT: If you modify this file, it's likely that the Learning gem5 book
+           also needs to be updated. For now, email Jason <power.jg@gmail.com>
+
+"""
+
+# import the m5 (gem5) library created when gem5 is built
+import m5
+# import all of the SimObjects
+from m5.objects import *
+
+# create the system we are going to simulate
+system = System()
+
+# Set the clock fequency of the system (and all of its children)
+system.clk_domain = SrcClockDomain()
+system.clk_domain.clock = '1GHz'
+system.clk_domain.voltage_domain = VoltageDomain()
+
+# Set up the system
+system.mem_mode = 'timing'               # Use timing accesses
+system.mem_ranges = [AddrRange('512MB')] # Create an address range
+
+# Create a simple CPU
+system.cpu = TimingSimpleCPU()
+
+# Create a memory bus, a system crossbar, in this case
+system.membus = SystemXBar()
+
+# Hook the CPU ports up to the membus
+system.cpu.icache_port = system.membus.slave
+system.cpu.dcache_port = system.membus.slave
+
+# create the interrupt controller for the CPU and connect to the membus
+system.cpu.createInterruptController()
+
+# For x86 only, make sure the interrupts are connected to the memory
+# Note: these are directly connected to the memory bus and are not cached
+if m5.defines.buildEnv['TARGET_ISA'] == "x86":
+    system.cpu.interrupts.pio = system.membus.master
+    system.cpu.interrupts.int_master = system.membus.slave
+    system.cpu.interrupts.int_slave = system.membus.master
+
+# Create a DDR3 memory controller and connect it to the membus
+system.mem_ctrl = DDR3_1600_x64()
+system.mem_ctrl.range = system.mem_ranges[0]
+system.mem_ctrl.port = system.membus.master
+
+# Connect the system up to the membus
+system.system_port = system.membus.slave
+
+# get ISA for the binary to run.
+isa = str(m5.defines.buildEnv['TARGET_ISA']).lower()
+
+# Run 'hello' and use the compiled ISA to find the binary
+binary = 'tests/test-progs/hello/bin/' + isa + '/linux/hello'
+
+# Create a process for a simple "Hello World" application
+process = LiveProcess()
+# Set the command
+# cmd is a list which begins with the executable (like argv)
+process.cmd = [binary]
+# Set the cpu to use the process as its workload and create thread contexts
+system.cpu.workload = process
+system.cpu.createThreads()
+
+# set up the root SimObject and start the simulation
+root = Root(full_system = False, system = system)
+# instantiate all of the objects we've created above
+m5.instantiate()
+
+print "Beginning simulation!"
+exit_event = m5.simulate()
+print 'Exiting @ tick %i because %s' % (m5.curTick(), exit_event.getCause())
diff --git a/configs/learning_gem5/part1/two_level.py b/configs/learning_gem5/part1/two_level.py
new file mode 100644
index 000000000..edaeafe79
--- /dev/null
+++ b/configs/learning_gem5/part1/two_level.py
@@ -0,0 +1,151 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2015 Jason Power
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met: redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer;
+# redistributions in binary form must reproduce the above copyright
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution;
+# neither the name of the copyright holders nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# Authors: Jason Power
+
+""" This file creates a single CPU and a two-level cache system.
+This script takes a single parameter which specifies a binary to execute.
+If none is provided it executes 'hello' by default (mostly used for testing)
+
+See Part 1, Chapter 3: Adding cache to the configuration script in the
+learning_gem5 book for more information about this script.
+This file exports options for the L1 I/D and L2 cache sizes.
+
+IMPORTANT: If you modify this file, it's likely that the Learning gem5 book
+           also needs to be updated. For now, email Jason <power.jg@gmail.com>
+
+"""
+
+# import the m5 (gem5) library created when gem5 is built
+import m5
+# import all of the SimObjects
+from m5.objects import *
+
+# Add the common scripts to our path
+m5.util.addToPath('../../common')
+
+# import the caches which we made
+from caches import *
+
+# import the SimpleOpts module
+import SimpleOpts
+
+# Set the usage message to display
+SimpleOpts.set_usage("usage: %prog [options] <binary to execute>")
+
+# Finalize the arguments and grab the opts so we can pass it on to our objects
+(opts, args) = SimpleOpts.parse_args()
+
+# get ISA for the default binary to run. This is mostly for simple testing
+isa = str(m5.defines.buildEnv['TARGET_ISA']).lower()
+
+# Default to running 'hello', use the compiled ISA to find the binary
+binary = 'tests/test-progs/hello/bin/' + isa + '/linux/hello'
+
+# Check if there was a binary passed in via the command line and error if
+# there are too many arguments
+if len(args) == 1:
+    binary = args[0]
+elif len(args) > 1:
+    SimpleOpts.print_help()
+    m5.fatal("Expected a binary to execute as positional argument")
+
+# create the system we are going to simulate
+system = System()
+
+# Set the clock fequency of the system (and all of its children)
+system.clk_domain = SrcClockDomain()
+system.clk_domain.clock = '1GHz'
+system.clk_domain.voltage_domain = VoltageDomain()
+
+# Set up the system
+system.mem_mode = 'timing'               # Use timing accesses
+system.mem_ranges = [AddrRange('512MB')] # Create an address range
+
+# Create a simple CPU
+system.cpu = TimingSimpleCPU()
+
+# Create an L1 instruction and data cache
+system.cpu.icache = L1ICache(opts)
+system.cpu.dcache = L1DCache(opts)
+
+# Connect the instruction and data caches to the CPU
+system.cpu.icache.connectCPU(system.cpu)
+system.cpu.dcache.connectCPU(system.cpu)
+
+# Create a memory bus, a coherent crossbar, in this case
+system.l2bus = L2XBar()
+
+# Hook the CPU ports up to the l2bus
+system.cpu.icache.connectBus(system.l2bus)
+system.cpu.dcache.connectBus(system.l2bus)
+
+# Create an L2 cache and connect it to the l2bus
+system.l2cache = L2Cache(opts)
+system.l2cache.connectCPUSideBus(system.l2bus)
+
+# Create a memory bus
+system.membus = SystemXBar()
+
+# Connect the L2 cache to the membus
+system.l2cache.connectMemSideBus(system.membus)
+
+# create the interrupt controller for the CPU
+system.cpu.createInterruptController()
+
+# For x86 only, make sure the interrupts are connected to the memory
+# Note: these are directly connected to the memory bus and are not cached
+if m5.defines.buildEnv['TARGET_ISA'] == "x86":
+    system.cpu.interrupts.pio = system.membus.master
+    system.cpu.interrupts.int_master = system.membus.slave
+    system.cpu.interrupts.int_slave = system.membus.master
+
+# Connect the system up to the membus
+system.system_port = system.membus.slave
+
+# Create a DDR3 memory controller
+system.mem_ctrl = DDR3_1600_x64()
+system.mem_ctrl.range = system.mem_ranges[0]
+system.mem_ctrl.port = system.membus.master
+
+# Create a process for a simple "Hello World" application
+process = LiveProcess()
+# Set the command
+# cmd is a list which begins with the executable (like argv)
+process.cmd = [binary]
+# Set the cpu to use the process as its workload and create thread contexts
+system.cpu.workload = process
+system.cpu.createThreads()
+
+# set up the root SimObject and start the simulation
+root = Root(full_system = False, system = system)
+# instantiate all of the objects we've created above
+m5.instantiate()
+
+print "Beginning simulation!"
+exit_event = m5.simulate()
+print 'Exiting @ tick %i because %s' % (m5.curTick(), exit_event.getCause())