<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<meta http-equiv="x-ua-compatible" content="ie=edge">
	<meta name="viewport" content="width=device-width, initial-scale=1">

	<title>gem5</title>

	<!-- SITE FAVICON -->
	<link rel="shortcut icon" type="image/gif" href="/assets/img/gem5ColorVert.gif"/>

	<link rel="canonical" href="http://localhost:4000/memoryobject/">
	<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,300,700,800,600' rel='stylesheet' type='text/css'>
	<link href='https://fonts.googleapis.com/css?family=Muli:400,300' rel='stylesheet' type='text/css'>

	<!-- FAVICON -->
	<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

	<!-- BOOTSTRAP -->
	<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/css/bootstrap.min.css" integrity="sha384-MCw98/SFnGE8fJT3GXwEOngsV7Zt27NXFoaoApmYm81iuXoPkFOJwJ8ERdknLPMO" crossorigin="anonymous">

	<!-- CUSTOM CSS -->
	<link rel="stylesheet" href="/css/main.css">
</head>


<body>
	<nav class="navbar navbar-expand-md navbar-light bg-light">
  <a class="navbar-brand" href="/">
		<img src="/assets/img/gem5ColorLong.gif" alt="gem5" height=45px>
	</a>
  <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false" aria-label="Toggle navigation">
    <span class="navbar-toggler-icon"></span>
  </button>
  <div class="collapse navbar-collapse" id="navbarNavDropdown">
    <ul class="navbar-nav ml-auto">
      <li class="nav-item ">
        <a class="nav-link" href="/">Home</a>
      </li>

			<li class="nav-item dropdown ">
				<a class="nav-link dropdown-toggle" href="/about" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					About
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
          <a class="dropdown-item" href="/about">About</a>
          <a class="dropdown-item" href="/publications">Publications</a>
          <a class="dropdown-item" href="/governance">Governance</a>
				</div>
			</li>

			<li class="nav-item dropdown active">
				<a class="nav-link dropdown-toggle" href="#" id="navbarDropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
					Documentation
				</a>
				<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
					<!-- Pull navigation from _data/documentation.yml -->
					
            <a class="dropdown-item" href="/introduction">Introduction</a>
					
            <a class="dropdown-item" href="/building">Getting Started</a>
					
            <a class="dropdown-item" href="/environment">Modifying/Extending</a>
					
            <a class="dropdown-item" href="/MSIintro">Modeling Cache Coherence with Ruby</a>
					
				</div>
			</li>

      <li class="nav-item ">
        <a class="nav-link" href="/contributing">Contributing</a>
      </li>

			<li class="nav-item ">
        <a class="nav-link" href="/search">Search</a>
      </li>
    </ul>
  </div>
</nav>

	<main>
		<div class="sidenav-top">
  <img src="/assets/img/gem5ColorLong.gif" height="80">
  <div class="search">
    <form action="/search" method="get">
      <!-- <label for="search-box"><i class="fa fa-search"></i></label> -->
      <input type="text" name="query">
      <button type="submit" name="submit"><i class="fa fa-search"></i></button>
    </form>
  </div>
</div>
<div class="sidenav">
  <!-- Pull navigation from _data/documentation.yml -->
  
    <a class="item" href="/introduction" role="button" aria-expanded="false" aria-controls="collapseExample">
      Introduction
    </a>
    <div class="collapse " id="introdution">
      
    </div>
  
    <a class="item" data-toggle="collapse" href="#pt1" role="button" aria-expanded="false" aria-controls="collapseExample">
      Getting Started
    </a>
    <div class="collapse " id="pt1">
      
        <a class="subitem " href="/building">Building gem5</a>
      
        <a class="subitem " href="/simple_config">Creating a simple configuration script</a>
      
        <a class="subitem " href="/cache_config">Adding cache to configuration script</a>
      
        <a class="subitem " href="/gem5_stats">Understanding gem5 statistics and output</a>
      
        <a class="subitem " href="/example_configs">Using the default configuration scripts</a>
      
    </div>
  
    <a class="item" data-toggle="collapse" href="#pt2" role="button" aria-expanded="false" aria-controls="collapseExample">
      Modifying/Extending
    </a>
    <div class="collapse show" id="pt2">
      
        <a class="subitem " href="/environment">Setting up your development environment</a>
      
        <a class="subitem " href="/helloobject">Creating a very simple SimObject</a>
      
        <a class="subitem " href="/debugging">Debugging gem5</a>
      
        <a class="subitem " href="/events">Event-driven programming</a>
      
        <a class="subitem " href="/parameters">Adding parameters to SimObjects and more events</a>
      
        <a class="subitem active" href="/memoryobject">Creating SimObjects in the memory system</a>
      
        <a class="subitem " href="/simplecache">Creating a simple cache object</a>
      
    </div>
  
    <a class="item" data-toggle="collapse" href="#pt3" role="button" aria-expanded="false" aria-controls="collapseExample">
      Modeling Cache Coherence with Ruby
    </a>
    <div class="collapse " id="pt3">
      
        <a class="subitem " href="/MSIintro">Introduction to Ruby</a>
      
        <a class="subitem " href="/cache-intro">MSI example cache protocol</a>
      
        <a class="subitem " href="/cache-declarations">Declaring a state machine</a>
      
        <a class="subitem " href="/cache-in-ports">In port code blocks</a>
      
        <a class="subitem " href="/cache-actions">Action code blocks</a>
      
        <a class="subitem " href="/cache-transitions">Transition code blocks</a>
      
        <a class="subitem " href="/directory">MSI Directory implementation</a>
      
        <a class="subitem " href="/MSIbuilding">Compiling a SLICC protocol</a>
      
        <a class="subitem " href="/configuration">Configuring a simple Ruby system</a>
      
        <a class="subitem " href="/running">Running the simple Ruby system</a>
      
        <a class="subitem " href="/MSIdebugging">Debugging SLICC Protocols</a>
      
        <a class="subitem " href="/simple-MI_example">Configuring for a standard protocol</a>
      
    </div>
  
</div>

<div class="container" id="doc-container">

  <!-- <h1>Creating SimObjects in the memory system</h1> -->
  <dl>
  <dt>authors</dt>
  <dd>Jason Lowe-Power</dd>
</dl>

<h1 id="creating-simobjects-in-the-memory-system">Creating SimObjects in the memory system</h1>

<p>In this chapter, we will create a simple memory object that sits between
the CPU and the memory bus. In the next chapter &lt;simplecache-chapter&gt;
we will take this simple memory object and add some logic to it to make
it a very simple blocking uniprocessor cache.</p>

<h2 id="gem5-master-and-slave-ports">gem5 master and slave ports</h2>

<p>Before diving into the implementation of a memory object, we should
first understand gem5’s master and slave port interface. As previously
discussed in simple-config-chapter, all memory objects are connected
together via ports. These ports provide a rigid interface between these
memory objects.</p>

<p>These ports implement three different memory system <em>modes</em>: timing,
atomic, and functional. The most important mode is <em>timing mode</em>. Timing
mode is the only mode that produces correct simulation results. The
other modes are only used in special circumstances.</p>

<p><em>Atomic mode</em> is useful for fastforwarding simulation to a region of
interest and warming up the simulator. This mode assumes that no events
will be generated in the memory system. Instead, all of the memory
requests execute through a single long callchain. It is not required to
implement atomic accesses for a memory object unless it will be used
during fastforward or during simulator warmup.</p>

<p><em>Functional mode</em> is better described as <em>debugging mode</em>. Functional
mode is used for things like reading data from the host into the
simulator memory. It is used heavily in syscall emulation mode. For
instance, functional mode is used to load the binary in the
<code class="highlighter-rouge">process.cmd</code> from the host into the simulated system’s memory so the
simulated system can access it. Functional accesses should return the
most up-to-date data on a read, no matter where the data is, and should
update all possible valid data on a write (e.g., in a system with caches
there may be multiple valid cache blocks with the same address).</p>

<h3 id="packets">Packets</h3>

<p>In gem5, <code class="highlighter-rouge">Packets</code> are sent across ports. A <code class="highlighter-rouge">Packet</code> is made up of a
<code class="highlighter-rouge">MemReq</code> which is the memory request object. The <code class="highlighter-rouge">MemReq</code> holds
information about the original request that initiated the packet such as
the requestor, the address, and the type of request (read, write, etc.).</p>

<p>Packets also have a <code class="highlighter-rouge">MemCmd</code>, which is the <em>current</em> command of the
packet. This command can change throughout the life of the packet (e.g.,
requests turn into responses once the memory command is satisfied). The
most common <code class="highlighter-rouge">MemCmd</code> are <code class="highlighter-rouge">ReadReq</code> (read request), <code class="highlighter-rouge">ReadResp</code> (read
response), <code class="highlighter-rouge">WriteReq</code> (write request), <code class="highlighter-rouge">WriteResp</code> (write response).
There are also writeback requests (<code class="highlighter-rouge">WritebackDirty</code>, <code class="highlighter-rouge">WritebackClean</code>)
for caches and many other command types.</p>

<p>Packets also either keep the data for the request, or a pointer to the
data. There are options when creating the packet whether the data is
dynamic (explicitly allocated and deallocated), or static (allocated and
deallocated by the packet object).</p>

<p>Finally, packets are used in the classic caches as the unit to track
coherency. Therefore, much of the packet code is specific to the classic
cache coherence protocol. However, packets are used for all
communication between memory objects in gem5, even if they are not
directly involved in coherence (e.g., DRAM controllers and the CPU
models).</p>

<p>All of the port interface functions accept a <code class="highlighter-rouge">Packet</code> pointer as a
parameter. Since this pointer is so common, gem5 includes a typedef for
it: <code class="highlighter-rouge">PacketPtr</code>.</p>

<h3 id="port-interface">Port interface</h3>

<p>There are two types of ports in gem5: master ports and slave ports.
Whenever you implement a memory object, you will implement at least one
of these types of ports. To do this, you create a new class that
inherits from either <code class="highlighter-rouge">MasterPort</code> or <code class="highlighter-rouge">SlavePort</code> for master and slave
ports, respectively. Master ports send requests (and receive response),
and slave ports receive requests (and send responses).</p>

<p>master-slave-1-fig outlines the simplest interaction between a master
and slave port. This figure shows the interaction in timing mode. The
other modes are much simpler and use a simple callchain between the
master and the slave.</p>

<p><img src="../_static/figures/master_slave_1.png" alt="Simple master-slave interaction when both can accept the request and
the response." /></p>

<p>As mentioned above, all of the port interfaces require a <code class="highlighter-rouge">PacketPtr</code> as
a parameter. Each of these functions (<code class="highlighter-rouge">sendTimingReq</code>, <code class="highlighter-rouge">recvTimingReq</code>,
etc.), accepts a single parameter, a <code class="highlighter-rouge">PacketPtr</code>. This packet is the
request or response to send or receive.</p>

<p>To send a request packet, the master calls <code class="highlighter-rouge">sendTimingReq</code>. In turn,
(and in the same callchain), the function <code class="highlighter-rouge">recvTimingReq</code> is called on
the slave with the same <code class="highlighter-rouge">PacketPtr</code> as its sole parameter.</p>

<p>The <code class="highlighter-rouge">recvTimingReq</code> has a return type of <code class="highlighter-rouge">bool</code>. This boolean return
value is directly returned to the calling master. A return value of
<code class="highlighter-rouge">true</code> signifies that the packet was accepted by the slave. A return
value of <code class="highlighter-rouge">false</code>, on the other hand, means that the slave was unable to
accept and the request must be retried sometime in the future.</p>

<p>In master-slave-1-fig, first, the master sends a timing request by
calling <code class="highlighter-rouge">sendTimingReq</code>, which in turn calls <code class="highlighter-rouge">recvTimingResp</code>. The
slave, returns true from <code class="highlighter-rouge">recvTimingResp</code>, which is returned from the
call to <code class="highlighter-rouge">sendTimingReq</code>. The master continue executing, and the slave
does whatever is necessary to complete the request (e.g., if it is a
cache, it looks up the tags to see if there is a match to the address in
the request).</p>

<p>Once the slave completes the request, it can send a response to the
master. The slave calls <code class="highlighter-rouge">sendTimingResp</code> with the response packet (this
should be the same <code class="highlighter-rouge">PacketPtr</code> as the request, but it should now be a
response packet). In turn, the master function <code class="highlighter-rouge">recvTimingResp</code> is
called. The master’s <code class="highlighter-rouge">recvTimingResp</code> function returns <code class="highlighter-rouge">true</code>, which is
the return value of <code class="highlighter-rouge">sendTimingResp</code> in the slave. Thus, the interaction
for that request is complete.</p>

<p>Later in master-slave-example-section we will show the example code for
these functions.</p>

<p>It is possible that the master or slave is busy when they receive a
request or a response. master-slave-2-fig shows the case where the slave
is busy when the original request was sent.</p>

<p><img src="../_static/figures/master_slave_2.png" alt="Simple master-slave interaction when the slave is
busy" /></p>

<p>In this case, the slave returns <code class="highlighter-rouge">false</code> from the <code class="highlighter-rouge">recvTimingReq</code>
function. When a master receives false after calling <code class="highlighter-rouge">sendTimingReq</code>, it
must wait until the its function <code class="highlighter-rouge">recvReqRetry</code> is executed. Only when
this function is called is the master allowed to retry calling
<code class="highlighter-rouge">sendTimingRequest</code>. The above figure shows the timing request failing
once, but it could fail any number of times. Note: it is up to the
master to track the packet that fails, not the slave. The slave <em>does
not</em> keep the pointer to the packet that fails.</p>

<p>Similarly, master-slave-3-fig shows the case when the master is busy at
the time the slave tries to send a response. In this case, the slave
cannot call <code class="highlighter-rouge">sendTimingResp</code> until it receives a <code class="highlighter-rouge">recvRespRetry</code>.</p>

<p><img src="../_static/figures/master_slave_3.png" alt="Simple master-slave interaction when the master is
busy" /></p>

<p>Importantly, in both of these cases, the retry codepath can be a single
call stack. For instance, when the master calls <code class="highlighter-rouge">sendRespRetry</code>,
<code class="highlighter-rouge">recvTimingReq</code> can also be called in the same call stack. Therefore, it
is easy to incorrectly create an infinite recursion bug, or other bugs.
It is important that before a memory object sends a retry, that it is
ready <em>at that instant</em> to accept another packet.</p>

<h2 id="simple-memory-object-example">Simple memory object example</h2>

<p>In this section, we will build a simple memory object. Initially, it
will simply pass requests through from the CPU-side (a simple CPU) to
the memory-side (a simple memory bus). See Figure simple-memobj-figure.
It will have a single master port, to send requests to the memory bus,
and two cpu-side ports for the instruction and data cache ports of the
CPU. In the next chapter &lt;simplecache-chapter&gt;, we will add the logic
to make this object a cache.</p>

<p><img src="../_static/figures/simple_memobj.png" alt="System with a simple memory object which sits between a CPU and the
memory bus." /></p>

<h3 id="declare-the-simobject">Declare the SimObject</h3>

<p>Just like when we were creating the simple SimObject in
hello-simobject-chapter, the first step is to create a SimObject Python
file. We will call this simple memory object <code class="highlighter-rouge">SimpleMemobj</code> and create
the SimObject Python file in <code class="highlighter-rouge">src/learning_gem5/simple_memobj</code>.</p>

<p>``` {.sourceCode .python}
from m5.params import *
from m5.proxy import *
from MemObject import MemObject</p>

<p>class SimpleMemobj(MemObject):
    type = ‘SimpleMemobj’
    cxx_header = “learning_gem5/simple_memobj/simple_memobj.hh”</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>inst_port = SlavePort("CPU side port, receives requests")
data_port = SlavePort("CPU side port, receives requests")
mem_side = MasterPort("Memory side port, sends requests") ```
</code></pre></div></div>

<p>For this object, we inherit from <code class="highlighter-rouge">MemObject</code>, not <code class="highlighter-rouge">SimObject</code> since we
are creating an object that will interact with the memory system. The
<code class="highlighter-rouge">MemObject</code> class has two pure virtual functions that we will have to
define in our C++ implementation, <code class="highlighter-rouge">getMasterPort</code> and <code class="highlighter-rouge">getSlavePort</code>.</p>

<p>This object’s parameters are three ports. Two ports for the CPU to
connect the instruction and data ports and a port to connect to the
memory bus. These ports do not have a default value, and they have a
simple description.</p>

<p>It is important to remember the names of these ports. We will explicitly
use these names when implementing <code class="highlighter-rouge">SimpleMemobj</code> and defining the
<code class="highlighter-rouge">getMasterPort</code> and <code class="highlighter-rouge">getSlavePort</code> functions.</p>

<p>You can download the SimObject file
here &lt;../_static/scripts/part2/memoryobject/SimpleMemobj.py&gt;</p>

<p>Of course, you also need to create a SConscript file in the new
directory as well that declares the SimObject Python file. You can
download the SConscript file
here &lt;../_static/scripts/part2/memoryobject/SConscript&gt;</p>

<h3 id="define-the-simplememobj-class">Define the SimpleMemobj class</h3>

<p>Now, we create a header file for <code class="highlighter-rouge">SimpleMemobj</code>.</p>

<p>``` {.sourceCode .c++}
class SimpleMemobj : public MemObject
{
  private:</p>

<p>public:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>/** constructor
 */
SimpleMemobj(SimpleMemobjParams *params); }; ```
</code></pre></div></div>

<h3 id="define-a-slave-port-type">Define a slave port type</h3>

<p>Now, we need to define classes for our two kinds of ports: the CPU-side
and the memory-side ports. For this, we will declare these classes
inside the <code class="highlighter-rouge">SimpleMemobj</code> class since no other object will ever use
these classes.</p>

<p>Let’s start with the slave port, or the CPU-side port. We are going to
inherit from the <code class="highlighter-rouge">SlavePort</code> class. The following is the required code
to override all of the pure virtual functions in the <code class="highlighter-rouge">SlavePort</code> class.</p>

<p>``` {.sourceCode .c++}
class CPUSidePort : public SlavePort
{
  private:
    SimpleMemobj *owner;</p>

<p>public:
    CPUSidePort(const std::string&amp; name, SimpleMemobj *owner) :
        SlavePort(name, owner), owner(owner)
    { }</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>AddrRangeList getAddrRanges() const override;
</code></pre></div></div>

<p>protected:
    Tick recvAtomic(PacketPtr pkt) override { panic(“recvAtomic unimpl.”); }
    void recvFunctional(PacketPtr pkt) override;
    bool recvTimingReq(PacketPtr pkt) override;
    void recvRespRetry() override;
};</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
This object requires five functions to be defined.

This object also has a single member variable, its owner, so it can call
functions on that object.

### Define a master port type

Next, we need to define a master port type. This will be the memory-side
port which will forward request from the CPU-side to the rest of the
memory system.

``` {.sourceCode .c++}
class MemSidePort : public MasterPort
{
  private:
    SimpleMemobj *owner;

  public:
    MemSidePort(const std::string&amp; name, SimpleMemobj *owner) :
        MasterPort(name, owner), owner(owner)
    { }

  protected:
    bool recvTimingResp(PacketPtr pkt) override;
    void recvReqRetry() override;
    void recvRangeChange() override;
};
</code></pre></div></div>

<p>This class only has three pure virtual functions that we must override.</p>

<h3 id="defining-the-memobject-interface">Defining the MemObject interface</h3>

<p>Now that we have defined these two new types <code class="highlighter-rouge">CPUSidePort</code> and
<code class="highlighter-rouge">MemSidePort</code>, we can declare our three ports as part of <code class="highlighter-rouge">SimpleMemobj</code>.
We also need to declare the two pure virtual functions in the
<code class="highlighter-rouge">MemObject</code> class, <code class="highlighter-rouge">getMasterPort</code> and <code class="highlighter-rouge">getSlavePort</code>. These two
functions are used by gem5 during the initialization phase to connect
memory objects together via ports.</p>

<p>``` {.sourceCode .c++}
class SimpleMemobj : public MemObject
{
  private:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;CPUSidePort declaration&gt;
&lt;MemSidePort declaration&gt;

CPUSidePort instPort;
CPUSidePort dataPort;

MemSidePort memPort;
</code></pre></div></div>

<p>public:
    SimpleMemobj(SimpleMemobjParams *params);</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>BaseMasterPort&amp; getMasterPort(const std::string&amp; if_name,
                              PortID idx = InvalidPortID) override;

BaseSlavePort&amp; getSlavePort(const std::string&amp; if_name,
                            PortID idx = InvalidPortID) override;
</code></pre></div></div>

<p>};</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
You can download the header file for the `SimpleMemobj`
here \&lt;../\_static/scripts/part2/memoryobject/simple\_memobj.hh\&gt;

### Implementing basic MemObject functions

For the constructor of `SimpleMemobj`, we will simply call the
`MemObject` constructor. We also need to initialize all of the ports.
Each port's constructor takes two parameters: the name and a pointer to
its owner, as we defined in the header file. The name can be any string,
but by convention, it is the same name as in the Python SimObject file.

``` {.sourceCode .c++}
SimpleMemobj::SimpleMemobj(SimpleMemobjParams *params) :
    MemObject(params),
    instPort(params-&gt;name + ".inst_port", this),
    dataPort(params-&gt;name + ".data_port", this),
    memPort(params-&gt;name + ".mem_side", this)
{
}
</code></pre></div></div>

<p>Next, we need to implement the interfaces to get the ports. This
interface is made of two functions <code class="highlighter-rouge">getMasterPort</code> and <code class="highlighter-rouge">getSlavePort</code>.
These functions take two parameters. The <code class="highlighter-rouge">if_name</code> is the Python
variable name of the interface for <em>this</em> object. In the case of the
master port it will be <code class="highlighter-rouge">mem_side</code> since this is what we declared as a
<code class="highlighter-rouge">MasterPort</code> in the Python SimObject file.</p>

<p>To implement <code class="highlighter-rouge">getMasterPort</code>, we compare the <code class="highlighter-rouge">if_name</code> and check to see
if it is <code class="highlighter-rouge">mem_side</code> as specified in our Python SimObject file. If it is,
then we return the <code class="highlighter-rouge">memPort</code> object. If not, then we pass the request
name to our parent. However, it will be an error if we try to connect a
slave port to any other named port since the parent class has no ports
defined.</p>

<p>``` {.sourceCode .c++}
BaseMasterPort&amp;
SimpleMemobj::getMasterPort(const std::string&amp; if_name, PortID idx)
{
    if (if_name == “mem_side”) {
        return memPort;
    } else {
        return MemObject::getMasterPort(if_name, idx);
    }
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
To implement `getSlavePort`, we similarly check if the `if_name` matches
either of the names we defined for our slave ports in the Python
SimObject file. If the name is `"inst_port"`, then we return the
instPort, and if the name is `data_port` we return the data port.

``` {.sourceCode .c++}
BaseSlavePort&amp;
SimpleMemobj::getSlavePort(const std::string&amp; if_name, PortID idx)
{
    if (if_name == "inst_port") {
        return instPort;
    } else if (if_name == "data_port") {
        return dataPort;
    } else {
        return MemObject::getSlavePort(if_name, idx);
    }
}
</code></pre></div></div>

<h3 id="implementing-slave-and-master-port-functions">Implementing slave and master port functions</h3>

<p>The implementation of both the slave and master port is relatively
simple. For the most part, each of the port functions just forwards the
information to the main memory object (<code class="highlighter-rouge">SimpleMemobj</code>).</p>

<p>Starting with two simple functions, <code class="highlighter-rouge">getAddrRanges</code> and <code class="highlighter-rouge">recvFunctional</code>
simply call into the <code class="highlighter-rouge">SimpleMemobj</code>.</p>

<p>``` {.sourceCode .c++}
AddrRangeList
SimpleMemobj::CPUSidePort::getAddrRanges() const
{
    return owner-&gt;getAddrRanges();
}</p>

<p>void
SimpleMemobj::CPUSidePort::recvFunctional(PacketPtr pkt)
{
    return owner-&gt;handleFunctional(pkt);
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
The implementation of these functions in the `SimpleMemobj` are equally
simple. These implementations just pass through the request to the
memory side. We can use `DPRINTF` calls here to track what is happening
for debug purposes as well.

``` {.sourceCode .c++}
void
SimpleMemobj::handleFunctional(PacketPtr pkt)
{
    memPort.sendFunctional(pkt);
}

AddrRangeList
SimpleMemobj::getAddrRanges() const
{
    DPRINTF(SimpleMemobj, "Sending new ranges\n");
    return memPort.getAddrRanges();
}
</code></pre></div></div>

<p>Similarly for the <code class="highlighter-rouge">MemSidePort</code>, we need to implement <code class="highlighter-rouge">recvRangeChange</code>
and forward the request through the <code class="highlighter-rouge">SimpleMemobj</code> to the slave port.</p>

<p>``` {.sourceCode .c++}
void
SimpleMemobj::MemSidePort::recvRangeChange()
{
    owner-&gt;sendRangeChange();
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
``` {.sourceCode .c++}
void
SimpleMemobj::sendRangeChange()
{
    instPort.sendRangeChange();
    dataPort.sendRangeChange();
}
</code></pre></div></div>

<h3 id="implementing-receiving-requests">Implementing receiving requests</h3>

<p>The implementation of <code class="highlighter-rouge">recvTimingReq</code> is slightly more complicated. We
need to check to see if the <code class="highlighter-rouge">SimpleMemobj</code> can accept the request. The
<code class="highlighter-rouge">SimpleMemobj</code> is a very simple blocking structure; we only allow a
single request outstanding at a time. Therefore, if we get a request
while another request is outstanding, the <code class="highlighter-rouge">SimpleMemobj</code> will block the
second request.</p>

<p>To simplify the implementation, the <code class="highlighter-rouge">CPUSidePort</code> stores all of the
flow-control information for the port interface. Thus, we need to add an
extra member variable, <code class="highlighter-rouge">needRetry</code>, to the <code class="highlighter-rouge">CPUSidePort</code>, a boolean that
stores whether we need to send a retry whenever the <code class="highlighter-rouge">SimpleMemobj</code>
becomes free. Then, if the <code class="highlighter-rouge">SimpleMemobj</code> is blocked on a request, we
set that we need to send a retry sometime in the future.</p>

<p>``` {.sourceCode .c++}
bool
SimpleMemobj::CPUSidePort::recvTimingReq(PacketPtr pkt)
{
    if (!owner-&gt;handleRequest(pkt)) {
        needRetry = true;
        return false;
    } else {
        return true;
    }
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
To handle the request for the `SimpleMemobj`, we first check if the
`SimpleMemobj` is already blocked waiting for a response to another
request. If it is blocked, then we return `false` to signal the calling
master port that we cannot accept the request right now. Otherwise, we
mark the port as blocked and send the packet out of the memory port. For
this, we can define a helper function in the `MemSidePort` object to
hide the flow control from the `SimpleMemobj` implementation. We will
assume the `memPort` handles all of the flow control and always return
`true` from `handleRequest` since we were successful in consuming the
request.

``` {.sourceCode .c++}
bool
SimpleMemobj::handleRequest(PacketPtr pkt)
{
    if (blocked) {
        return false;
    }
    DPRINTF(SimpleMemobj, "Got request for addr %#x\n", pkt-&gt;getAddr());
    blocked = true;
    memPort.sendPacket(pkt);
    return true;
}
</code></pre></div></div>

<p>Next, we need to implement the <code class="highlighter-rouge">sendPacket</code> function in the
<code class="highlighter-rouge">MemSidePort</code>. This function will handle the flow control in case its
peer slave port cannot accept the request. For this, we need to add a
member to the <code class="highlighter-rouge">MemSidePort</code> to store the packet in case it is blocked.
It is the responsibility of the sender to store the packet if the
receiver cannot receive the request (or response).</p>

<p>This function simply send the packet by calling the function
<code class="highlighter-rouge">sendTimingReq</code>. If the send fails, then this object store the packet in
the <code class="highlighter-rouge">blockedPacket</code> member function so it can send the packet later
(when it receives a <code class="highlighter-rouge">recvReqRetry</code>). This function also contains some
defensive code to make sure there is not a bug and we never try to
overwrite the <code class="highlighter-rouge">blockedPacket</code> variable incorrectly.</p>

<p>``` {.sourceCode .c++}
void
SimpleMemobj::MemSidePort::sendPacket(PacketPtr pkt)
{
    panic_if(blockedPacket != nullptr, “Should never try to send if blocked!”);
    if (!sendTimingReq(pkt)) {
        blockedPacket = pkt;
    }
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
Next, we need to implement the code to resend the packet. In this
function, we try to resend the packet by calling the `sendPacket`
function we wrote above.

``` {.sourceCode .c++}
void
SimpleMemobj::MemSidePort::recvReqRetry()
{
    assert(blockedPacket != nullptr);

    PacketPtr pkt = blockedPacket;
    blockedPacket = nullptr;

    sendPacket(pkt);
}
</code></pre></div></div>

<h3 id="implementing-receiving-responses">Implementing receiving responses</h3>

<p>The response codepath is similar to the receiving codepath. When the
<code class="highlighter-rouge">MemSidePort</code> gets a response, we forward the response through the
<code class="highlighter-rouge">SimpleMemobj</code> to the appropriate <code class="highlighter-rouge">CPUSidePort</code>.</p>

<p>``` {.sourceCode .c++}
bool
SimpleMemobj::MemSidePort::recvTimingResp(PacketPtr pkt)
{
    return owner-&gt;handleResponse(pkt);
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
In the `SimpleMemobj`, first, it should always be blocked when we
receive a response since the object is blocking. Before sending the
packet back to the CPU side, we need to mark that the object no longer
blocked. This must be done *before calling `sendTimingResp`*. Otherwise,
it is possible to get stuck in an infinite loop as it is possible that
the master port has a single callchain between receiving a response and
sending another request.

After unblocking the `SimpleMemobj`, we check to see if the packet is an
instruction or data packet and send it back across the appropriate port.
Finally, since the object is now unblocked, we may need to notify the
CPU side ports that they can now retry their requests that failed.

``` {.sourceCode .c++}
bool
SimpleMemobj::handleResponse(PacketPtr pkt)
{
    assert(blocked);
    DPRINTF(SimpleMemobj, "Got response for addr %#x\n", pkt-&gt;getAddr());

    blocked = false;

    // Simply forward to the memory port
    if (pkt-&gt;req-&gt;isInstFetch()) {
        instPort.sendPacket(pkt);
    } else {
        dataPort.sendPacket(pkt);
    }

    instPort.trySendRetry();
    dataPort.trySendRetry();

    return true;
}
</code></pre></div></div>

<p>Similar to how we implemented a convenience function for sending packets
in the <code class="highlighter-rouge">MemSidePort</code>, we can implement a <code class="highlighter-rouge">sendPacket</code> function in the
<code class="highlighter-rouge">CPUSidePort</code> to send the responses to the CPU side. This function calls
<code class="highlighter-rouge">sendTimingResp</code> which will in turn call <code class="highlighter-rouge">recvTimingResp</code> on the peer
master port. If this call fails and the peer port is currently blocked,
then we store the packet to be sent later.</p>

<p>``` {.sourceCode .c++}
void
SimpleMemobj::CPUSidePort::sendPacket(PacketPtr pkt)
{
    panic_if(blockedPacket != nullptr, “Should never try to send if blocked!”);</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>if (!sendTimingResp(pkt)) {
    blockedPacket = pkt;
} } ```
</code></pre></div></div>

<p>We will send this blocked packet later when we receive a
<code class="highlighter-rouge">recvRespRetry</code>. This function is exactly the same as the <code class="highlighter-rouge">recvReqRetry</code>
above and simply tries to resend the packet, which may be blocked again.</p>

<p>``` {.sourceCode .c++}
void
SimpleMemobj::CPUSidePort::recvRespRetry()
{
    assert(blockedPacket != nullptr);</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>PacketPtr pkt = blockedPacket;
blockedPacket = nullptr;

sendPacket(pkt); } ```
</code></pre></div></div>

<p>Finally, we need to implement the extra function <code class="highlighter-rouge">trySendRetry</code> for the
<code class="highlighter-rouge">CPUSidePort</code>. This function is called by the <code class="highlighter-rouge">SimpleMemobj</code> whenever
the <code class="highlighter-rouge">SimpleMemobj</code> may be unblocked. <code class="highlighter-rouge">trySendRetry</code> checks to see if a
retry is needed which we marked in <code class="highlighter-rouge">recvTimingReq</code> whenever the
<code class="highlighter-rouge">SimpleMemobj</code> was blocked on a new request. Then, if the retry is
needed, this function calls <code class="highlighter-rouge">sendRetryReq</code>, which in turn calls
<code class="highlighter-rouge">recvReqRetry</code> on the peer master port (the CPU in this case).</p>

<p>``` {.sourceCode .c++}
void
SimpleMemobj::CPUSidePort::trySendRetry()
{
    if (needRetry &amp;&amp; blockedPacket == nullptr) {
        needRetry = false;
        DPRINTF(SimpleMemobj, “Sending retry req for %d\n”, id);
        sendRetryReq();
    }
}</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
You can download the implementation for the `SimpleMemobj`
here \&lt;../\_static/scripts/part2/memoryobject/simple\_memobj.cc\&gt;

The following figure, memobj-api-figure, shows the relationships between
the `CPUSidePort`, `MemSidePort`, and `SimpleMemobj`. This figure shows
how the peer ports interact with the implementation of the
`SimpleMemobj`. Each bold function is one that we had to implement, and
the non-bold functions are the port interfaces to the peer ports. The
colors highlight one API path through the object (e.g., receiving a
request or updating the memory ranges).

![](../_static/figures/memobj_api.png)

&gt; width
&gt; :   100 %
&gt;
&gt; alt
&gt; :   Interaction between SimpleMemobj and its ports
&gt;
&gt; Interaction between SimpleMemobj and its ports

For this simple memory object, packets are just forwarded from the
CPU-side to the memory side. However, by modifying `handleRequest` and
`handleResponse`, we can create rich featureful objects, like a cache in
the next chapter \&lt;simplecache-chapter\&gt;.

### Create a config file

This is all of the code needed to implement a simple memory object! In
the next chapter \&lt;simplecache-chapter\&gt;, we will take this framework
and add some caching logic to make this memory object into a simple
cache. However, before that, let's look at the config file to add the
SimpleMemobj to your system.

This config file builds off of the simple config file in
simple-config-chapter. However, instead of connecting the CPU directly
to the memory bus, we are going to instantiate a `SimpleMemobj` and
place it between the CPU and the memory bus.

``` {.sourceCode .python}
import m5
from m5.objects import *

system = System()
system.clk_domain = SrcClockDomain()
system.clk_domain.clock = '1GHz'
system.clk_domain.voltage_domain = VoltageDomain()
system.mem_mode = 'timing'
system.mem_ranges = [AddrRange('512MB')]

system.cpu = TimingSimpleCPU()

system.memobj = SimpleMemobj()

system.cpu.icache_port = system.memobj.inst_port
system.cpu.dcache_port = system.memobj.data_port

system.membus = SystemXBar()

system.memobj.mem_side = system.membus.slave

system.cpu.createInterruptController()
system.cpu.interrupts[0].pio = system.membus.master
system.cpu.interrupts[0].int_master = system.membus.slave
system.cpu.interrupts[0].int_slave = system.membus.master

system.mem_ctrl = DDR3_1600_8x8()
system.mem_ctrl.range = system.mem_ranges[0]
system.mem_ctrl.port = system.membus.master

system.system_port = system.membus.slave

process = Process()
process.cmd = ['tests/test-progs/hello/bin/x86/linux/hello']
system.cpu.workload = process
system.cpu.createThreads()

root = Root(full_system = False, system = system)
m5.instantiate()

print "Beginning simulation!"
exit_event = m5.simulate()
print 'Exiting @ tick %i because %s' % (m5.curTick(), exit_event.getCause())
</code></pre></div></div>

<p>You can download this config script
here &lt;../_static/scripts/part2/memoryobject/simple_memobj.py&gt;</p>

<p>Now, when you run this config file you get the following output.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem5 Simulator System.  http://gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 compiled Jan  5 2017 13:40:18
gem5 started Jan  9 2017 10:17:17
gem5 executing on chinook, pid 5138
command line: build/X86/gem5.opt configs/learning_gem5/part2/simple_memobj.py

Global frequency set at 1000000000000 ticks per second
warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes)
0: system.remote_gdb.listener: listening for remote gdb #0 on port 7000
warn: CoherentXBar system.membus has no snooping ports attached!
warn: ClockedObject: More than one power state change request encountered within the same simulation tick
Beginning simulation!
info: Entering event queue @ 0.  Starting simulation...
Hello world!
Exiting @ tick 507841000 because target called exit()
</code></pre></div></div>

<p>If you run with the <code class="highlighter-rouge">SimpleMemobj</code> debug flag, you can see all of the
memory requests and responses from and to the CPU.</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gem5 Simulator System.  http://gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 compiled Jan  5 2017 13:40:18
gem5 started Jan  9 2017 10:18:51
gem5 executing on chinook, pid 5157
command line: build/X86/gem5.opt --debug-flags=SimpleMemobj configs/learning_gem5/part2/simple_memobj.py

Global frequency set at 1000000000000 ticks per second
Beginning simulation!
info: Entering event queue @ 0.  Starting simulation...
      0: system.memobj: Got request for addr 0x190
  77000: system.memobj: Got response for addr 0x190
  77000: system.memobj: Got request for addr 0x190
 132000: system.memobj: Got response for addr 0x190
 132000: system.memobj: Got request for addr 0x190
 187000: system.memobj: Got response for addr 0x190
 187000: system.memobj: Got request for addr 0x94e30
 250000: system.memobj: Got response for addr 0x94e30
 250000: system.memobj: Got request for addr 0x190
 ...
</code></pre></div></div>

<p>You may also want to change the CPU model to the out-of-order model
(<code class="highlighter-rouge">DerivO3CPU</code>). When using the out-of-order CPU you will potentially see
a different address stream since it allows multiple memory requests
outstanding at a once. When using the out-of-order CPU, there will now
be many stalls because the <code class="highlighter-rouge">SimpleMemobj</code> is blocking.</p>


</div>

	</main>

	<script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
	<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js" integrity="sha384-ZMP7rVo3mIykV+2+9J3UJ46jBk0WLaUAdn689aCwoqbBJiSnjAK/l8WvCWPIPm49" crossorigin="anonymous"></script>
	<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.1.3/js/bootstrap.min.js" integrity="sha384-ChfqqxuZUCnJSK3+MXmPNIyE6ZbWh2IMqE241rYiqJxyMiZ6OW/JmZQ5stwEULTy" crossorigin="anonymous"></script>

	<script>
	  // When the user scrolls down 20px from the top of the document, show the button
	  window.onscroll = function() {scrollFunction()};

	  function scrollFunction() {
	      if (document.body.scrollTop > 100 || document.documentElement.scrollTop > 20) {
	          document.getElementById("myBtn").style.display = "block";
	      } else {
	          document.getElementById("myBtn").style.display = "none";
	      }
	  }

	  // When the user clicks on the button, scroll to the top of the document
	  function topFunction() {
	      document.body.scrollTop = 0;
	      document.documentElement.scrollTop = 0;
	  }
	</script>

</body>

<footer class="page-footer">
	<div class="container">
		<div class="row">

			<div class="col-12 col-sm-4">
				<p><a href="/about">About</a></p>
				<p><a href="/publications">Publications</a></p>
				<p><a href="/contributing">Contributing</a></p>
			</div><br>

			<div class="col-12 col-sm-4">
				<p><a href="/gettingstarted">Documentation</a></p>
				<p><a href="#">Source</a></p>
			</div><br>

			<div class="col-12 col-sm-4">
				<p><a href="/help">Help</a></p>
				<p><a href="/search">Search</a></p>
				<p><a href="#">Mailing Lists</a></p>
			</div>

		</div>
	</div>
</footer>


</html>