learning_gem5: Add code for hello-goodbye example

Adding more code from Learning gem5 Part II

See http://learning.gem5.org/book/part2/parameters.html

Change-Id: I9fe5655239e011c718c5cf5fd62bebcda66ea966
Signed-off-by: Jason Lowe-Power <jason@lowepower.com>
Reviewed-on: https://gem5-review.googlesource.com/5021
Reviewed-by: Nikos Nikoleris <nikos.nikoleris@arm.com>

7 files changed, 449 insertions, 0 deletions

diff --git a/configs/learning_gem5/part2/hello_goodbye.py b/configs/learning_gem5/part2/hello_goodbye.py
new file mode 100644
index 000000000..6e82a63c7
--- /dev/null
+++ b/configs/learning_gem5/part2/hello_goodbye.py
@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2017 Jason Lowe-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 Lowe-Power
+
+"""
+A simple run file that creates two SimObjects: HelloObject and GoodbyeObject
+and then runs the simulation. Using the debug "Hello" is informative.
+
+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 *
+
+# set up the root SimObject and start the simulation
+root = Root(full_system = False)
+
+# Create an instantiation of the simobject you created
+root.hello = HelloObject(time_to_wait = '2us', number_of_fires = 5)
+root.hello.goodbye_object = GoodbyeObject(buffer_size='100B')
+
+# 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/src/learning_gem5/part2/HelloObject.py b/src/learning_gem5/part2/HelloObject.py
new file mode 100644
index 000000000..42f1be319
--- /dev/null
+++ b/src/learning_gem5/part2/HelloObject.py
@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2017 Jason Lowe-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 Lowe-Power
+
+from m5.params import *
+from m5.SimObject import SimObject
+
+class HelloObject(SimObject):
+    type = 'HelloObject'
+    cxx_header = "learning_gem5/part2/hello_object.hh"
+
+    time_to_wait = Param.Latency("Time before firing the event")
+    number_of_fires = Param.Int(1, "Number of times to fire the event before "
+                                   "goodbye")
+
+    goodbye_object = Param.GoodbyeObject("A goodbye object")
+
+class GoodbyeObject(SimObject):
+    type = 'GoodbyeObject'
+    cxx_header = "learning_gem5/part2/goodbye_object.hh"
+
+    buffer_size = Param.MemorySize('1kB',
+                                   "Size of buffer to fill with goodbye")
+    write_bandwidth = Param.MemoryBandwidth('100MB/s', "Bandwidth to fill "
+                                            "the buffer")
diff --git a/src/learning_gem5/part2/SConscript b/src/learning_gem5/part2/SConscript
index f32fa0fb7..35d14ecce 100644
--- a/src/learning_gem5/part2/SConscript
+++ b/src/learning_gem5/part2/SConscript
@@ -30,5 +30,10 @@
 Import('*')
 
 SimObject('SimpleObject.py')
+SimObject('HelloObject.py')
 
 Source('simple_object.cc')
+Source('hello_object.cc')
+Source('goodbye_object.cc')
+
+DebugFlag('HelloExample', "For Learning gem5 Part 2. Simple example debug flag")
diff --git a/src/learning_gem5/part2/goodbye_object.cc b/src/learning_gem5/part2/goodbye_object.cc
new file mode 100644
index 000000000..3eaa5adb6
--- /dev/null
+++ b/src/learning_gem5/part2/goodbye_object.cc
@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2017 Jason Lowe-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 Lowe-Power
+ */
+
+#include "learning_gem5/part2/goodbye_object.hh"
+
+#include "debug/HelloExample.hh"
+#include "sim/sim_exit.hh"
+
+GoodbyeObject::GoodbyeObject(GoodbyeObjectParams *params) :
+    SimObject(params), event([this]{ processEvent(); }, name() + ".event"),
+    bandwidth(params->write_bandwidth), bufferSize(params->buffer_size),
+    buffer(nullptr), bufferUsed(0)
+{
+    buffer = new char[bufferSize];
+    DPRINTF(HelloExample, "Created the goodbye object\n");
+}
+
+GoodbyeObject::~GoodbyeObject()
+{
+    delete[] buffer;
+}
+
+void
+GoodbyeObject::processEvent()
+{
+    DPRINTF(HelloExample, "Processing the event!\n");
+
+    // Actually do the "work" of the event
+    fillBuffer();
+}
+
+void
+GoodbyeObject::sayGoodbye(std::string other_name)
+{
+    DPRINTF(HelloExample, "Saying goodbye to %s\n", other_name);
+
+    message = "Goodbye " + other_name + "!! ";
+
+    // Kick off the the first buffer fill. If it can't fill the whole buffer
+    // because of a limited bandwidth, then this function will schedule another
+    // event to finish the fill
+    fillBuffer();
+}
+
+void
+GoodbyeObject::fillBuffer()
+{
+    // There better be a message
+    assert(message.length() > 0);
+
+    // Copy from the message to the buffer per byte.
+    int bytes_copied = 0;
+    for (auto it = message.begin();
+         it < message.end() && bufferUsed < bufferSize - 1;
+         it++, bufferUsed++, bytes_copied++) {
+        // Copy the character into the buffer
+        buffer[bufferUsed] = *it;
+    }
+
+    if (bufferUsed < bufferSize - 1) {
+        // Wait for the next copy for as long as it would have taken
+        DPRINTF(HelloExample, "Scheduling another fillBuffer in %d ticks\n",
+                bandwidth * bytes_copied);
+        schedule(event, curTick() + bandwidth * bytes_copied);
+    } else {
+        DPRINTF(HelloExample, "Goodbye done copying!\n");
+        // Be sure to take into account the time for the last bytes
+        exitSimLoop(buffer, 0, curTick() + bandwidth * bytes_copied);
+    }
+}
+
+GoodbyeObject*
+GoodbyeObjectParams::create()
+{
+    return new GoodbyeObject(this);
+}
diff --git a/src/learning_gem5/part2/goodbye_object.hh b/src/learning_gem5/part2/goodbye_object.hh
new file mode 100644
index 000000000..0a2453ceb
--- /dev/null
+++ b/src/learning_gem5/part2/goodbye_object.hh
@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2017 Jason Lowe-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 Lowe-Power
+ */
+
+#ifndef __LEARNING_GEM5_GOODBYE_OBJECT_HH__
+#define __LEARNING_GEM5_GOODBYE_OBJECT_HH__
+
+#include <string>
+
+#include "params/GoodbyeObject.hh"
+#include "sim/sim_object.hh"
+
+class GoodbyeObject : public SimObject
+{
+  private:
+    /**
+     * Fill the buffer with the next chunk of data
+     */
+    void processEvent();
+
+    /// An event that wraps the above function
+    EventFunctionWrapper event;
+
+    /**
+     * Fills the buffer for one iteration. If the buffer isn't full, this
+     * function will enqueue another event to continue filling.
+     */
+    void fillBuffer();
+
+    /// The bytes processed per tick
+    float bandwidth;
+
+    /// The size of the buffer we are going to fill
+    int bufferSize;
+
+    /// The buffer we are putting our message in
+    char *buffer;
+
+    /// The message to put into the buffer.
+    std::string message;
+
+    /// The amount of the buffer we've used so far.
+    int bufferUsed;
+
+  public:
+    GoodbyeObject(GoodbyeObjectParams *p);
+    ~GoodbyeObject();
+
+    /**
+     * Called by an outside object. Starts off the events to fill the buffer
+     * with a goodbye message.
+     *
+     * @param name the name of the object we are saying goodbye to.
+     */
+    void sayGoodbye(std::string name);
+};
+
+#endif // __LEARNING_GEM5_GOODBYE_OBJECT_HH__
diff --git a/src/learning_gem5/part2/hello_object.cc b/src/learning_gem5/part2/hello_object.cc
new file mode 100644
index 000000000..b52a4cef7
--- /dev/null
+++ b/src/learning_gem5/part2/hello_object.cc
@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2017 Jason Lowe-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 Lowe-Power
+ */
+
+#include "learning_gem5/part2/hello_object.hh"
+
+#include "base/misc.hh"
+#include "debug/HelloExample.hh"
+
+HelloObject::HelloObject(HelloObjectParams *params) :
+    SimObject(params),
+    // This is a C++ lambda. When the event is triggered, it will call the
+    // processEvent() function. (this must be captured)
+    event([this]{ processEvent(); }, name() + ".event"),
+    goodbye(params->goodbye_object),
+    // Note: This is not needed as you can *always* reference this->name()
+    myName(params->name),
+    latency(params->time_to_wait),
+    timesLeft(params->number_of_fires)
+{
+    DPRINTF(HelloExample, "Created the hello object\n");
+    panic_if(!goodbye, "HelloObject must have a non-null GoodbyeObject");
+}
+
+void
+HelloObject::startup()
+{
+    // Before simulation starts, we need to schedule the event
+    schedule(event, latency);
+}
+
+void
+HelloObject::processEvent()
+{
+    timesLeft--;
+    DPRINTF(HelloExample, "Hello world! Processing the event! %d left\n",
+                          timesLeft);
+
+    if (timesLeft <= 0) {
+        DPRINTF(HelloExample, "Done firing!\n");
+        goodbye->sayGoodbye(myName);
+    } else {
+        schedule(event, curTick() + latency);
+    }
+}
+
+HelloObject*
+HelloObjectParams::create()
+{
+    return new HelloObject(this);
+}
diff --git a/src/learning_gem5/part2/hello_object.hh b/src/learning_gem5/part2/hello_object.hh
new file mode 100644
index 000000000..09c9585f9
--- /dev/null
+++ b/src/learning_gem5/part2/hello_object.hh
@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) 2017 Jason Lowe-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 Lowe-Power
+ */
+
+#ifndef __LEARNING_GEM5_HELLO_OBJECT_HH__
+#define __LEARNING_GEM5_HELLO_OBJECT_HH__
+
+#include <string>
+
+#include "learning_gem5/part2/goodbye_object.hh"
+#include "params/HelloObject.hh"
+#include "sim/sim_object.hh"
+
+class HelloObject : public SimObject
+{
+  private:
+    /**
+     * Example function to execute on an event trigger
+     */
+    void processEvent();
+
+    /// An event that wraps the above function
+    EventFunctionWrapper event;
+
+    /// Pointer to the corresponding GoodbyeObject. Set via Python
+    GoodbyeObject* goodbye;
+
+    /// The name of this object in the Python config file
+    const std::string myName;
+
+    /// Latency between calling the event (in ticks)
+    const Tick latency;
+
+    /// Number of times left to fire the event before goodbye
+    int timesLeft;
+
+  public:
+    HelloObject(HelloObjectParams *p);
+
+    /**
+     * Part of a SimObject's initilaization. Startup is called after all
+     * SimObjects have been constructed. It is called after the user calls
+     * simulate() for the first time.
+     */
+    void startup();
+};
+
+#endif // __LEARNING_GEM5_HELLO_OBJECT_HH__