1/*
2 * Copyright (c) 2011-2012,2015,2017 ARM Limited
3 * All rights reserved
4 *
5 * The license below extends only to copyright in the software and shall
6 * not be construed as granting a license to any other intellectual
7 * property including but not limited to intellectual property relating
8 * to a hardware implementation of the functionality of the software
9 * licensed hereunder.  You may use the software subject to the license
10 * terms below provided that you ensure that this notice is replicated
11 * unmodified and in its entirety in all distributions of the software,
12 * modified or unmodified, in source code or in binary form.
13 *
14 * Copyright (c) 2002-2005 The Regents of The University of Michigan
15 * All rights reserved.
16 *
17 * Redistribution and use in source and binary forms, with or without
18 * modification, are permitted provided that the following conditions are
19 * met: redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer;
21 * redistributions in binary form must reproduce the above copyright
22 * notice, this list of conditions and the following disclaimer in the
23 * documentation and/or other materials provided with the distribution;
24 * neither the name of the copyright holders nor the names of its
25 * contributors may be used to endorse or promote products derived from
26 * this software without specific prior written permission.
27 *
28 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39 *
40 * Authors: Ron Dreslinski
41 *          Andreas Hansson
42 *          William Wang
43 */
44
45#ifndef __MEM_GEM5_PROTOCOL_TIMING_HH__
46#define __MEM_GEM5_PROTOCOL_TIMING_HH__
47
48#include "mem/packet.hh"
49
50class TimingResponseProtocol;
51
52class TimingRequestProtocol
53{
54    friend class TimingResponseProtocol;
55
56  protected:
57    /**
58     * Attempt to send a timing request to the peer by calling
59     * its corresponding receive function. If the send does not
60     * succeed, as indicated by the return value, then the sender must
61     * wait for a recvReqRetry at which point it can re-issue a
62     * sendTimingReq.
63     *
64     * @param peer Peer to send packet to.
65     * @param pkt Packet to send.
66     *
67     * @return If the send was succesful or not.
68     */
69    bool sendReq(TimingResponseProtocol *peer, PacketPtr pkt);
70
71    /**
72     * Check if the peer can handle a timing request.
73     *
74     * If the send cannot be handled at the moment, as indicated by
75     * the return value, then the sender will receive a recvReqRetry
76     * at which point it can re-issue a sendTimingReq.
77     *
78     * @param peer Peer to send packet to.
79     * @param pkt Packet to send.
80     *
81     * @return If the send was succesful or not.
82     */
83    bool trySend(TimingResponseProtocol *peer, PacketPtr pkt) const;
84
85    /**
86     * Attempt to send a timing snoop response packet to it's peer
87     * by calling its corresponding receive function. If the send
88     * does not succeed, as indicated by the return value, then the
89     * sender must wait for a recvRetrySnoop at which point it can
90     * re-issue a sendTimingSnoopResp.
91     *
92     * @param pkt Packet to send.
93     */
94    bool sendSnoopResp(TimingResponseProtocol *peer, PacketPtr pkt);
95
96    /**
97     * Send a retry to the peer that previously attempted a
98     * sendTimingResp to this protocol and failed.
99     */
100    void sendRetryResp(TimingResponseProtocol *peer);
101
102    /**
103     * Receive a timing response from the peer.
104     */
105    virtual bool recvTimingResp(PacketPtr pkt) = 0;
106
107    /**
108     * Receive a timing snoop request from the peer.
109     */
110    virtual void recvTimingSnoopReq(PacketPtr pkt) = 0;
111
112    /**
113     * Called by the peer if sendTimingReq was called on this peer (causing
114     * recvTimingReq to be called on the peer) and was unsuccessful.
115     */
116    virtual void recvReqRetry() = 0;
117
118    /**
119     * Called by the peer if sendTimingSnoopResp was called on this
120     * protocol (causing recvTimingSnoopResp to be called on the peer)
121     * and was unsuccessful.
122     */
123    virtual void recvRetrySnoopResp() = 0;
124};
125
126class TimingResponseProtocol
127{
128    friend class TimingRequestProtocol;
129
130  protected:
131    /**
132     * Attempt to send a timing response to the peer by calling
133     * its corresponding receive function. If the send does not
134     * succeed, as indicated by the return value, then the sender must
135     * wait for a recvRespRetry at which point it can re-issue a
136     * sendTimingResp.
137     *
138     * @param peer Peer to send the packet to.
139     * @param pkt Packet to send.
140     *
141     * @return If the send was succesful or not.
142    */
143    bool sendResp(TimingRequestProtocol *peer, PacketPtr pkt);
144
145    /**
146     * Attempt to send a timing snoop request packet to the peer
147     * by calling its corresponding receive function. Snoop requests
148     * always succeed and hence no return value is needed.
149     *
150     * @param peer Peer to send the packet to.
151     * @param pkt Packet to send.
152     */
153    void sendSnoopReq(TimingRequestProtocol *peer, PacketPtr pkt);
154
155    /**
156     * Send a retry to the peer that previously attempted a
157     * sendTimingReq to this protocol and failed.
158     */
159    void sendRetryReq(TimingRequestProtocol *peer);
160
161    /**
162     * Send a retry to the peer that previously attempted a
163     * sendTimingSnoopResp to this peer and failed.
164     */
165    void sendRetrySnoopResp(TimingRequestProtocol *peer);
166
167    /**
168     * Receive a timing request from the peer.
169     */
170    virtual bool recvTimingReq(PacketPtr pkt) = 0;
171
172    /**
173     * Availability request from the peer.
174     */
175    virtual bool tryTiming(PacketPtr pkt) = 0;
176
177    /**
178     * Receive a timing snoop response from the peer.
179     */
180    virtual bool recvTimingSnoopResp(PacketPtr pkt) = 0;
181
182    /**
183     * Called by the peer if sendTimingResp was called on this
184     * protocol (causing recvTimingResp to be called on the peer)
185     * and was unsuccessful.
186     */
187    virtual void recvRespRetry() = 0;
188};
189
190#endif //__MEM_GEM5_PROTOCOL_TIMING_HH__
191