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/**
46 * @file
47 * Port Object Declaration.
48 */
49
50#ifndef __MEM_PORT_HH__
51#define __MEM_PORT_HH__
52
53#include "base/addr_range.hh"
54#include "mem/packet.hh"
55#include "mem/protocol/atomic.hh"
56#include "mem/protocol/functional.hh"
57#include "mem/protocol/timing.hh"
58#include "sim/port.hh"
59
60class SimObject;
61
62/** Forward declaration */
63class BaseSlavePort;
64
65/**
66 * A BaseMasterPort is a protocol-agnostic master port, responsible
67 * only for the structural connection to a slave port. The final
68 * master port that inherits from the base class must override the
69 * bind member function for the specific slave port class.
70 */
71class BaseMasterPort : public Port
72{
73 protected:
74 BaseSlavePort *_baseSlavePort;
75
76 BaseMasterPort(const std::string &name, PortID id=InvalidPortID);
77 virtual ~BaseMasterPort();
78
79 public:
80 BaseSlavePort& getSlavePort() const;
81 void bind(Port &peer) override;
82 void unbind() override;
83};
84
85/**
86 * A BaseSlavePort is a protocol-agnostic slave port, responsible
87 * only for the structural connection to a master port.
88 */
89class BaseSlavePort : public Port
90{
91 protected:
92 BaseMasterPort *_baseMasterPort;
93
94 BaseSlavePort(const std::string &name, PortID id=InvalidPortID);
95 virtual ~BaseSlavePort();
96
97 public:
98 BaseMasterPort& getMasterPort() const;
99 void bind(Port &peer) override;
100 void unbind() override;
101};
102
103/** Forward declaration */
104class SlavePort;
105
106/**
107 * A MasterPort is a specialisation of a BaseMasterPort, which
108 * implements the default protocol for the three different level of
109 * transport functions. In addition to the basic functionality of
110 * sending packets, it also has functions to receive range changes or
111 * determine if the port is snooping or not.
112 *
113 * The three protocols are atomic, timing, and functional, each with its own
114 * header file.
115 */
116class MasterPort : public BaseMasterPort, public AtomicRequestProtocol,
117 public TimingRequestProtocol, public FunctionalRequestProtocol
118{
119 friend class SlavePort;
120
121 private:
122 SlavePort *_slavePort;
123
124 protected:
125 SimObject &owner;
126
127 public:
128 MasterPort(const std::string& name, SimObject* _owner,
129 PortID id=InvalidPortID);
130 virtual ~MasterPort();
131
132 /**
133 * Bind this master port to a slave port. This also does the
134 * mirror action and binds the slave port to the master port.
135 */
136 void bind(Port &peer) override;
137
138 /**
139 * Unbind this master port and the associated slave port.
140 */
141 void unbind() override;
142
143 /**
144 * Determine if this master port is snooping or not. The default
145 * implementation returns false and thus tells the neighbour we
146 * are not snooping. Any master port that wants to receive snoop
147 * requests (e.g. a cache connected to a bus) has to override this
148 * function.
149 *
150 * @return true if the port should be considered a snooper
151 */
152 virtual bool isSnooping() const { return false; }
153
154 /**
155 * Get the address ranges of the connected slave port.
156 */
157 AddrRangeList getAddrRanges() const;
158
159 /**
160 * Inject a PrintReq for the given address to print the state of
161 * that address throughout the memory system. For debugging.
162 */
163 void printAddr(Addr a);
164
165 public:
166 /* The atomic protocol. */
167
168 /**
169 * Send an atomic request packet, where the data is moved and the
170 * state is updated in zero time, without interleaving with other
171 * memory accesses.
172 *
173 * @param pkt Packet to send.
174 *
175 * @return Estimated latency of access.
176 */
177 Tick sendAtomic(PacketPtr pkt);
178
179 /**
180 * Send an atomic request packet like above, but also request a backdoor
181 * to the data being accessed.
182 *
183 * @param pkt Packet to send.
184 * @param backdoor Can be set to a back door pointer by the target to let
185 * caller have direct access to the requested data.
186 *
187 * @return Estimated latency of access.
188 */
189 Tick sendAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor);
190
191 public:
192 /* The functional protocol. */
193
194 /**
195 * Send a functional request packet, where the data is instantly
196 * updated everywhere in the memory system, without affecting the
197 * current state of any block or moving the block.
198 *
199 * @param pkt Packet to send.
200 */
201 void sendFunctional(PacketPtr pkt) const;
202
203 public:
204 /* The timing protocol. */
205
206 /**
207 * Attempt to send a timing request to the slave port by calling
208 * its corresponding receive function. If the send does not
209 * succeed, as indicated by the return value, then the sender must
210 * wait for a recvReqRetry at which point it can re-issue a
211 * sendTimingReq.
212 *
213 * @param pkt Packet to send.
214 *
215 * @return If the send was succesful or not.
216 */
217 bool sendTimingReq(PacketPtr pkt);
218
219 /**
220 * Check if the slave can handle a timing request.
221 *
222 * If the send cannot be handled at the moment, as indicated by
223 * the return value, then the sender will receive a recvReqRetry
224 * at which point it can re-issue a sendTimingReq.
225 *
226 * @param pkt Packet to send.
227 *
228 * @return If the send was succesful or not.
229 */
230 bool tryTiming(PacketPtr pkt) const;
231
232 /**
233 * Attempt to send a timing snoop response packet to the slave
234 * port by calling its corresponding receive function. If the send
235 * does not succeed, as indicated by the return value, then the
236 * sender must wait for a recvRetrySnoop at which point it can
237 * re-issue a sendTimingSnoopResp.
238 *
239 * @param pkt Packet to send.
240 */
241 bool sendTimingSnoopResp(PacketPtr pkt);
242
243 /**
244 * Send a retry to the slave port that previously attempted a
245 * sendTimingResp to this master port and failed. Note that this
246 * is virtual so that the "fake" snoop response port in the
247 * coherent crossbar can override the behaviour.
248 */
249 virtual void sendRetryResp();
250
251 protected:
252 /**
253 * Called to receive an address range change from the peer slave
254 * port. The default implementation ignores the change and does
255 * nothing. Override this function in a derived class if the owner
256 * needs to be aware of the address ranges, e.g. in an
257 * interconnect component like a bus.
258 */
259 virtual void recvRangeChange() { }
260
261 /**
262 * Default implementations.
263 */
264 Tick
265 recvAtomicSnoop(PacketPtr pkt) override
266 {
267 panic("%s was not expecting an atomic snoop request\n", name());
268 return 0;
269 }
270
271 void
272 recvFunctionalSnoop(PacketPtr pkt) override
273 {
274 panic("%s was not expecting a functional snoop request\n", name());
275 }
276
277 void
278 recvTimingSnoopReq(PacketPtr pkt) override
279 {
280 panic("%s was not expecting a timing snoop request.\n", name());
281 }
282
283 void
284 recvRetrySnoopResp() override
285 {
286 panic("%s was not expecting a snoop retry.\n", name());
287 }
288};
289
290/**
291 * A SlavePort is a specialisation of a port. In addition to the
292 * basic functionality of sending packets to its master peer, it also
293 * has functions specific to a slave, e.g. to send range changes
294 * and get the address ranges that the port responds to.
295 *
296 * The three protocols are atomic, timing, and functional, each with its own
297 * header file.
298 */
299class SlavePort : public BaseSlavePort, public AtomicResponseProtocol,
300 public TimingResponseProtocol, public FunctionalResponseProtocol
301{
302 friend class MasterPort;
303
304 private:
305 MasterPort* _masterPort;
306 bool defaultBackdoorWarned;
307
308 protected:
309 SimObject& owner;
310
311 public:
312 SlavePort(const std::string& name, SimObject* _owner,
313 PortID id=InvalidPortID);
314 virtual ~SlavePort();
315
316 /**
317 * Find out if the peer master port is snooping or not.
318 *
319 * @return true if the peer master port is snooping
320 */
321 bool isSnooping() const { return _masterPort->isSnooping(); }
322
323 /**
324 * Called by the owner to send a range change
325 */
326 void
327 sendRangeChange() const
328 {
329 fatal_if(!_masterPort,
330 "%s cannot sendRangeChange() without master port.", name());
331 _masterPort->recvRangeChange();
332 }
333
334 /**
335 * Get a list of the non-overlapping address ranges the owner is
336 * responsible for. All slave ports must override this function
337 * and return a populated list with at least one item.
338 *
339 * @return a list of ranges responded to
340 */
341 virtual AddrRangeList getAddrRanges() const = 0;
342
343 /**
344 * We let the master port do the work, so these don't do anything.
345 */
346 void unbind() override {}
347 void bind(Port &peer) override {}
348
349 public:
350 /* The atomic protocol. */
351
352 /**
353 * Send an atomic snoop request packet, where the data is moved
354 * and the state is updated in zero time, without interleaving
355 * with other memory accesses.
356 *
357 * @param pkt Snoop packet to send.
358 *
359 * @return Estimated latency of access.
360 */
361 Tick
362 sendAtomicSnoop(PacketPtr pkt)
363 {
364 return AtomicResponseProtocol::sendSnoop(_masterPort, pkt);
365 }
366
367 public:
368 /* The functional protocol. */
369
370 /**
371 * Send a functional snoop request packet, where the data is
372 * instantly updated everywhere in the memory system, without
373 * affecting the current state of any block or moving the block.
374 *
375 * @param pkt Snoop packet to send.
376 */
377 void
378 sendFunctionalSnoop(PacketPtr pkt) const
379 {
380 FunctionalResponseProtocol::sendSnoop(_masterPort, pkt);
381 }
382
383 public:
384 /* The timing protocol. */
385
386 /**
387 * Attempt to send a timing response to the master port by calling
388 * its corresponding receive function. If the send does not
389 * succeed, as indicated by the return value, then the sender must
390 * wait for a recvRespRetry at which point it can re-issue a
391 * sendTimingResp.
392 *
393 * @param pkt Packet to send.
394 *
395 * @return If the send was succesful or not.
396 */
397 bool
398 sendTimingResp(PacketPtr pkt)
399 {
400 return TimingResponseProtocol::sendResp(_masterPort, pkt);
401 }
402
403 /**
404 * Attempt to send a timing snoop request packet to the master port
405 * by calling its corresponding receive function. Snoop requests
406 * always succeed and hence no return value is needed.
407 *
408 * @param pkt Packet to send.
409 */
410 void
411 sendTimingSnoopReq(PacketPtr pkt)
412 {
413 TimingResponseProtocol::sendSnoopReq(_masterPort, pkt);
414 }
415
416 /**
417 * Send a retry to the master port that previously attempted a
418 * sendTimingReq to this slave port and failed.
419 */
420 void
421 sendRetryReq()
422 {
423 TimingResponseProtocol::sendRetryReq(_masterPort);
424 }
425
426 /**
427 * Send a retry to the master port that previously attempted a
428 * sendTimingSnoopResp to this slave port and failed.
429 */
430 void
431 sendRetrySnoopResp()
432 {
433 TimingResponseProtocol::sendRetrySnoopResp(_masterPort);
434 }
435
436 protected:
437 /**
438 * Called by the master port to unbind. Should never be called
439 * directly.
440 */
441 void slaveUnbind();
442
443 /**
444 * Called by the master port to bind. Should never be called
445 * directly.
446 */
447 void slaveBind(MasterPort& master_port);
448
449 /**
450 * Default implementations.
451 */
452 Tick recvAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor) override;
453
454 bool
455 tryTiming(PacketPtr pkt) override
456 {
457 panic("%s was not expecting a %s\n", name(), __func__);
458 }
459
460 bool
461 recvTimingSnoopResp(PacketPtr pkt) override
462 {
463 panic("%s was not expecting a timing snoop response\n", name());
464 }
465};
466
467inline Tick
468MasterPort::sendAtomic(PacketPtr pkt)
469{
470 return AtomicRequestProtocol::send(_slavePort, pkt);
471}
472
473inline Tick
474MasterPort::sendAtomicBackdoor(PacketPtr pkt, MemBackdoorPtr &backdoor)
475{
476 return AtomicRequestProtocol::sendBackdoor(_slavePort, pkt, backdoor);
477}
478
479inline void
480MasterPort::sendFunctional(PacketPtr pkt) const
481{
482 return FunctionalRequestProtocol::send(_slavePort, pkt);
483}
484
485inline bool
486MasterPort::sendTimingReq(PacketPtr pkt)
487{
488 return TimingRequestProtocol::sendReq(_slavePort, pkt);
489}
490
491inline bool
492MasterPort::tryTiming(PacketPtr pkt) const
493{
494 return TimingRequestProtocol::trySend(_slavePort, pkt);
495}
496
497inline bool
498MasterPort::sendTimingSnoopResp(PacketPtr pkt)
499{
500 return TimingRequestProtocol::sendSnoopResp(_slavePort, pkt);
501}
502
503inline void
504MasterPort::sendRetryResp()
505{
506 TimingRequestProtocol::sendRetryResp(_slavePort);
507}
508
509#endif //__MEM_PORT_HH__