src/mem/token_port.hh

   1 /*
   2  * Copyright (c) 2016-2020 Advanced Micro Devices, Inc.
   3  * All rights reserved.
   4  *
   5  * For use for simulation and test purposes only
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright notice,
  11  * this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright notice,
  14  * this list of conditions and the following disclaimer in the documentation
  15  * and/or other materials provided with the distribution.
  16  *
  17  * 3. Neither the name of the copyright holder nor the names of its
  18  * contributors may be used to endorse or promote products derived from this
  19  * software without specific prior written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  22  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  25  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  26  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  27  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  28  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  29  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  30  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  31  * POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 #ifndef __MEM_TOKEN_PORT_HH__
  35 #define __MEM_TOKEN_PORT_HH__
  36
  37 #include "mem/port.hh"
  38 #include "sim/clocked_object.hh"
  39
  40 class TokenManager;
  41 class TokenResponsePort;
  42
  43 class TokenRequestPort : public RequestPort
  44 {
  45   private:
  46     /* Manager to track tokens between this token port pair. */
  47     TokenManager *tokenManager;
  48
  49   public:
  50     TokenRequestPort(const std::string& name, SimObject* owner,
  51                     PortID id = InvalidPortID) :
  52         RequestPort(name, owner, id), tokenManager(nullptr)
  53     { }
  54
  55     /**
  56      * Bind this request port to response port. Called by the response port in
  57      * this token implementation.
  58      */
  59     void bind(Port &peer) override;
  60
  61     /**
  62      * Unbind port. Handled by response port in token implementation.
  63      */
  64     void unbind() override {}
  65
  66     /**
  67      * Receive tokens returned by the response port. This increments the number
  68      * or available tokens across the port.
  69      */
  70     void recvTokens(int num_tokens);
  71
  72     /**
  73      * Query if there are at least num_tokens tokens available to acquire.
  74      */
  75     bool haveTokens(int num_tokens);
  76
  77     /**
  78      * Acquire tokens by decrementing the number of available tokens across
  79      * the port. This does the opposite of recvTokens.
  80      */
  81     void acquireTokens(int num_tokens);
  82
  83     /**
  84      * Specify a token manger, which will handle tracking of tokens for a
  85      * TokenRequestPort/ResponseRequestPort pair.
  86      */
  87     void setTokenManager(TokenManager *_tokenManager);
  88 };
  89
  90 class TokenResponsePort : public ResponsePort
  91 {
  92   private:
  93     TokenRequestPort *tokenRequestPort;
  94
  95     std::deque<PacketPtr> respQueue;
  96
  97     void recvRespRetry() override;
  98
  99   public:
 100     TokenResponsePort(const std::string& name, ClockedObject *owner,
 101                    PortID id = InvalidPortID) :
 102         ResponsePort(name, owner, id), tokenRequestPort(nullptr)
 103     { }
 104     ~TokenResponsePort() { }
 105
 106     /**
 107      * Bind this response port to a request port. This also does the mirror
 108      * action and binds the request port to the response port as well as
 109      * binding the base class types.
 110      */
 111     void bind(Port &peer) override;
 112
 113     /**
 114      * Unbind this response port and associated request port.
 115      */
 116     void unbind() override;
 117
 118     /**
 119      * Return num_tokens tokens back to the request port.
 120      */
 121     void sendTokens(int num_tokens);
 122
 123     bool sendTimingResp(PacketPtr pkt);
 124
 125     /* There is no storage here so the packet will not be found. */
 126     bool trySatisfyFunctional(PacketPtr) { return false; }
 127 };
 128
 129 class TokenManager
 130 {
 131   protected:
 132     /* Maximum tokens possible */
 133     int maxTokens;
 134
 135     /* Number of currently available tokens */
 136     int availableTokens;
 137
 138   public:
 139     TokenManager(int init_tokens);
 140     ~TokenManager() { }
 141
 142     /**
 143      * Return the maximum possible tokens.
 144      */
 145     int getMaxTokenCount() const;
 146
 147     /**
 148      * Increment the number of available tokens by num_tokens.
 149      */
 150     void recvTokens(int num_tokens);
 151
 152     /**
 153      * Query is num_tokens tokens are available.
 154      */
 155     bool haveTokens(int num_tokens);
 156
 157     /**
 158      * Decrement the number of available tokens by num_tokens.
 159      */
 160     void acquireTokens(int num_tokens);
 161 };
 162
 163 #endif