packet.hh revision 11294
1/*
2 * Copyright (c) 2012-2015 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) 2006 The Regents of The University of Michigan
15 * Copyright (c) 2010,2015 Advanced Micro Devices, Inc.
16 * All rights reserved.
17 *
18 * Redistribution and use in source and binary forms, with or without
19 * modification, are permitted provided that the following conditions are
20 * met: redistributions of source code must retain the above copyright
21 * notice, this list of conditions and the following disclaimer;
22 * redistributions in binary form must reproduce the above copyright
23 * notice, this list of conditions and the following disclaimer in the
24 * documentation and/or other materials provided with the distribution;
25 * neither the name of the copyright holders nor the names of its
26 * contributors may be used to endorse or promote products derived from
27 * this software without specific prior written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
30 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
31 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
32 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
33 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
34 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
35 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
36 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
37 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
38 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
39 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 *
41 * Authors: Ron Dreslinski
42 *          Steve Reinhardt
43 *          Ali Saidi
44 *          Andreas Hansson
45 */
46
47/**
48 * @file
49 * Declaration of the Packet class.
50 */
51
52#ifndef __MEM_PACKET_HH__
53#define __MEM_PACKET_HH__
54
55#include <bitset>
56#include <cassert>
57#include <list>
58
59#include "base/cast.hh"
60#include "base/compiler.hh"
61#include "base/flags.hh"
62#include "base/misc.hh"
63#include "base/printable.hh"
64#include "base/types.hh"
65#include "mem/request.hh"
66#include "sim/core.hh"
67
68class Packet;
69typedef Packet *PacketPtr;
70typedef uint8_t* PacketDataPtr;
71typedef std::list<PacketPtr> PacketList;
72
73class MemCmd
74{
75    friend class Packet;
76
77  public:
78    /**
79     * List of all commands associated with a packet.
80     */
81    enum Command
82    {
83        InvalidCmd,
84        ReadReq,
85        ReadResp,
86        ReadRespWithInvalidate,
87        WriteReq,
88        WriteResp,
89        WritebackDirty,
90        WritebackClean,
91        CleanEvict,
92        SoftPFReq,
93        HardPFReq,
94        SoftPFResp,
95        HardPFResp,
96        WriteLineReq,
97        UpgradeReq,
98        SCUpgradeReq,           // Special "weak" upgrade for StoreCond
99        UpgradeResp,
100        SCUpgradeFailReq,       // Failed SCUpgradeReq in MSHR (never sent)
101        UpgradeFailResp,        // Valid for SCUpgradeReq only
102        ReadExReq,
103        ReadExResp,
104        ReadCleanReq,
105        ReadSharedReq,
106        LoadLockedReq,
107        StoreCondReq,
108        StoreCondFailReq,       // Failed StoreCondReq in MSHR (never sent)
109        StoreCondResp,
110        SwapReq,
111        SwapResp,
112        MessageReq,
113        MessageResp,
114        MemFenceReq,
115        MemFenceResp,
116        // Error responses
117        // @TODO these should be classified as responses rather than
118        // requests; coding them as requests initially for backwards
119        // compatibility
120        InvalidDestError,  // packet dest field invalid
121        BadAddressError,   // memory address invalid
122        FunctionalReadError, // unable to fulfill functional read
123        FunctionalWriteError, // unable to fulfill functional write
124        // Fake simulator-only commands
125        PrintReq,       // Print state matching address
126        FlushReq,      //request for a cache flush
127        InvalidateReq,   // request for address to be invalidated
128        InvalidateResp,
129        NUM_MEM_CMDS
130    };
131
132  private:
133    /**
134     * List of command attributes.
135     */
136    enum Attribute
137    {
138        IsRead,         //!< Data flows from responder to requester
139        IsWrite,        //!< Data flows from requester to responder
140        IsUpgrade,
141        IsInvalidate,
142        NeedsWritable,  //!< Requires writable copy to complete in-cache
143        IsRequest,      //!< Issued by requester
144        IsResponse,     //!< Issue by responder
145        NeedsResponse,  //!< Requester needs response from target
146        IsEviction,
147        IsSWPrefetch,
148        IsHWPrefetch,
149        IsLlsc,         //!< Alpha/MIPS LL or SC access
150        HasData,        //!< There is an associated payload
151        IsError,        //!< Error response
152        IsPrint,        //!< Print state matching address (for debugging)
153        IsFlush,        //!< Flush the address from caches
154        NUM_COMMAND_ATTRIBUTES
155    };
156
157    /**
158     * Structure that defines attributes and other data associated
159     * with a Command.
160     */
161    struct CommandInfo
162    {
163        /// Set of attribute flags.
164        const std::bitset<NUM_COMMAND_ATTRIBUTES> attributes;
165        /// Corresponding response for requests; InvalidCmd if no
166        /// response is applicable.
167        const Command response;
168        /// String representation (for printing)
169        const std::string str;
170    };
171
172    /// Array to map Command enum to associated info.
173    static const CommandInfo commandInfo[];
174
175  private:
176
177    Command cmd;
178
179    bool
180    testCmdAttrib(MemCmd::Attribute attrib) const
181    {
182        return commandInfo[cmd].attributes[attrib] != 0;
183    }
184
185  public:
186
187    bool isRead() const            { return testCmdAttrib(IsRead); }
188    bool isWrite() const           { return testCmdAttrib(IsWrite); }
189    bool isUpgrade() const         { return testCmdAttrib(IsUpgrade); }
190    bool isRequest() const         { return testCmdAttrib(IsRequest); }
191    bool isResponse() const        { return testCmdAttrib(IsResponse); }
192    bool needsWritable() const     { return testCmdAttrib(NeedsWritable); }
193    bool needsResponse() const     { return testCmdAttrib(NeedsResponse); }
194    bool isInvalidate() const      { return testCmdAttrib(IsInvalidate); }
195    bool isEviction() const        { return testCmdAttrib(IsEviction); }
196
197    /**
198     * A writeback is an eviction that carries data.
199     */
200    bool isWriteback() const       { return testCmdAttrib(IsEviction) &&
201                                            testCmdAttrib(HasData); }
202
203    /**
204     * Check if this particular packet type carries payload data. Note
205     * that this does not reflect if the data pointer of the packet is
206     * valid or not.
207     */
208    bool hasData() const        { return testCmdAttrib(HasData); }
209    bool isLLSC() const         { return testCmdAttrib(IsLlsc); }
210    bool isSWPrefetch() const   { return testCmdAttrib(IsSWPrefetch); }
211    bool isHWPrefetch() const   { return testCmdAttrib(IsHWPrefetch); }
212    bool isPrefetch() const     { return testCmdAttrib(IsSWPrefetch) ||
213                                         testCmdAttrib(IsHWPrefetch); }
214    bool isError() const        { return testCmdAttrib(IsError); }
215    bool isPrint() const        { return testCmdAttrib(IsPrint); }
216    bool isFlush() const        { return testCmdAttrib(IsFlush); }
217
218    Command
219    responseCommand() const
220    {
221        return commandInfo[cmd].response;
222    }
223
224    /// Return the string to a cmd given by idx.
225    const std::string &toString() const { return commandInfo[cmd].str; }
226    int toInt() const { return (int)cmd; }
227
228    MemCmd(Command _cmd) : cmd(_cmd) { }
229    MemCmd(int _cmd) : cmd((Command)_cmd) { }
230    MemCmd() : cmd(InvalidCmd) { }
231
232    bool operator==(MemCmd c2) const { return (cmd == c2.cmd); }
233    bool operator!=(MemCmd c2) const { return (cmd != c2.cmd); }
234};
235
236/**
237 * A Packet is used to encapsulate a transfer between two objects in
238 * the memory system (e.g., the L1 and L2 cache).  (In contrast, a
239 * single Request travels all the way from the requester to the
240 * ultimate destination and back, possibly being conveyed by several
241 * different Packets along the way.)
242 */
243class Packet : public Printable
244{
245  public:
246    typedef uint32_t FlagsType;
247    typedef ::Flags<FlagsType> Flags;
248
249  private:
250
251    enum : FlagsType {
252        // Flags to transfer across when copying a packet
253        COPY_FLAGS             = 0x0000000F,
254
255        // Does this packet have sharers (which means it should not be
256        // considered writable) or not. See setHasSharers below.
257        HAS_SHARERS            = 0x00000001,
258
259        // Special control flags
260        /// Special timing-mode atomic snoop for multi-level coherence.
261        EXPRESS_SNOOP          = 0x00000002,
262
263        /// Allow a responding cache to inform the cache hierarchy
264        /// that it had a writable copy before responding. See
265        /// setResponderHadWritable below.
266        RESPONDER_HAD_WRITABLE = 0x00000004,
267
268        // Snoop co-ordination flag to indicate that a cache is
269        // responding to a snoop. See setCacheResponding below.
270        CACHE_RESPONDING       = 0x00000008,
271
272        /// Are the 'addr' and 'size' fields valid?
273        VALID_ADDR             = 0x00000100,
274        VALID_SIZE             = 0x00000200,
275
276        /// Is the data pointer set to a value that shouldn't be freed
277        /// when the packet is destroyed?
278        STATIC_DATA            = 0x00001000,
279        /// The data pointer points to a value that should be freed when
280        /// the packet is destroyed. The pointer is assumed to be pointing
281        /// to an array, and delete [] is consequently called
282        DYNAMIC_DATA           = 0x00002000,
283
284        /// suppress the error if this packet encounters a functional
285        /// access failure.
286        SUPPRESS_FUNC_ERROR    = 0x00008000,
287
288        // Signal block present to squash prefetch and cache evict packets
289        // through express snoop flag
290        BLOCK_CACHED          = 0x00010000
291    };
292
293    Flags flags;
294
295  public:
296    typedef MemCmd::Command Command;
297
298    /// The command field of the packet.
299    MemCmd cmd;
300
301    /// A pointer to the original request.
302    const RequestPtr req;
303
304  private:
305   /**
306    * A pointer to the data being transfered.  It can be differnt
307    * sizes at each level of the heirarchy so it belongs in the
308    * packet, not request. This may or may not be populated when a
309    * responder recieves the packet. If not populated it memory should
310    * be allocated.
311    */
312    PacketDataPtr data;
313
314    /// The address of the request.  This address could be virtual or
315    /// physical, depending on the system configuration.
316    Addr addr;
317
318    /// True if the request targets the secure memory space.
319    bool _isSecure;
320
321    /// The size of the request or transfer.
322    unsigned size;
323
324    /**
325     * Track the bytes found that satisfy a functional read.
326     */
327    std::vector<bool> bytesValid;
328
329  public:
330
331    /**
332     * The extra delay from seeing the packet until the header is
333     * transmitted. This delay is used to communicate the crossbar
334     * forwarding latency to the neighbouring object (e.g. a cache)
335     * that actually makes the packet wait. As the delay is relative,
336     * a 32-bit unsigned should be sufficient.
337     */
338    uint32_t headerDelay;
339
340    /**
341     * Keep track of the extra delay incurred by snooping upwards
342     * before sending a request down the memory system. This is used
343     * by the coherent crossbar to account for the additional request
344     * delay.
345     */
346    uint32_t snoopDelay;
347
348    /**
349     * The extra pipelining delay from seeing the packet until the end of
350     * payload is transmitted by the component that provided it (if
351     * any). This includes the header delay. Similar to the header
352     * delay, this is used to make up for the fact that the
353     * crossbar does not make the packet wait. As the delay is
354     * relative, a 32-bit unsigned should be sufficient.
355     */
356    uint32_t payloadDelay;
357
358    /**
359     * A virtual base opaque structure used to hold state associated
360     * with the packet (e.g., an MSHR), specific to a MemObject that
361     * sees the packet. A pointer to this state is returned in the
362     * packet's response so that the MemObject in question can quickly
363     * look up the state needed to process it. A specific subclass
364     * would be derived from this to carry state specific to a
365     * particular sending device.
366     *
367     * As multiple MemObjects may add their SenderState throughout the
368     * memory system, the SenderStates create a stack, where a
369     * MemObject can add a new Senderstate, as long as the
370     * predecessing SenderState is restored when the response comes
371     * back. For this reason, the predecessor should always be
372     * populated with the current SenderState of a packet before
373     * modifying the senderState field in the request packet.
374     */
375    struct SenderState
376    {
377        SenderState* predecessor;
378        SenderState() : predecessor(NULL) {}
379        virtual ~SenderState() {}
380    };
381
382    /**
383     * Object used to maintain state of a PrintReq.  The senderState
384     * field of a PrintReq should always be of this type.
385     */
386    class PrintReqState : public SenderState
387    {
388      private:
389        /**
390         * An entry in the label stack.
391         */
392        struct LabelStackEntry
393        {
394            const std::string label;
395            std::string *prefix;
396            bool labelPrinted;
397            LabelStackEntry(const std::string &_label, std::string *_prefix);
398        };
399
400        typedef std::list<LabelStackEntry> LabelStack;
401        LabelStack labelStack;
402
403        std::string *curPrefixPtr;
404
405      public:
406        std::ostream &os;
407        const int verbosity;
408
409        PrintReqState(std::ostream &os, int verbosity = 0);
410        ~PrintReqState();
411
412        /**
413         * Returns the current line prefix.
414         */
415        const std::string &curPrefix() { return *curPrefixPtr; }
416
417        /**
418         * Push a label onto the label stack, and prepend the given
419         * prefix string onto the current prefix.  Labels will only be
420         * printed if an object within the label's scope is printed.
421         */
422        void pushLabel(const std::string &lbl,
423                       const std::string &prefix = "  ");
424
425        /**
426         * Pop a label off the label stack.
427         */
428        void popLabel();
429
430        /**
431         * Print all of the pending unprinted labels on the
432         * stack. Called by printObj(), so normally not called by
433         * users unless bypassing printObj().
434         */
435        void printLabels();
436
437        /**
438         * Print a Printable object to os, because it matched the
439         * address on a PrintReq.
440         */
441        void printObj(Printable *obj);
442    };
443
444    /**
445     * This packet's sender state.  Devices should use dynamic_cast<>
446     * to cast to the state appropriate to the sender.  The intent of
447     * this variable is to allow a device to attach extra information
448     * to a request. A response packet must return the sender state
449     * that was attached to the original request (even if a new packet
450     * is created).
451     */
452    SenderState *senderState;
453
454    /**
455     * Push a new sender state to the packet and make the current
456     * sender state the predecessor of the new one. This should be
457     * prefered over direct manipulation of the senderState member
458     * variable.
459     *
460     * @param sender_state SenderState to push at the top of the stack
461     */
462    void pushSenderState(SenderState *sender_state);
463
464    /**
465     * Pop the top of the state stack and return a pointer to it. This
466     * assumes the current sender state is not NULL. This should be
467     * preferred over direct manipulation of the senderState member
468     * variable.
469     *
470     * @return The current top of the stack
471     */
472    SenderState *popSenderState();
473
474    /**
475     * Go through the sender state stack and return the first instance
476     * that is of type T (as determined by a dynamic_cast). If there
477     * is no sender state of type T, NULL is returned.
478     *
479     * @return The topmost state of type T
480     */
481    template <typename T>
482    T * findNextSenderState() const
483    {
484        T *t = NULL;
485        SenderState* sender_state = senderState;
486        while (t == NULL && sender_state != NULL) {
487            t = dynamic_cast<T*>(sender_state);
488            sender_state = sender_state->predecessor;
489        }
490        return t;
491    }
492
493    /// Return the string name of the cmd field (for debugging and
494    /// tracing).
495    const std::string &cmdString() const { return cmd.toString(); }
496
497    /// Return the index of this command.
498    inline int cmdToIndex() const { return cmd.toInt(); }
499
500    bool isRead() const              { return cmd.isRead(); }
501    bool isWrite() const             { return cmd.isWrite(); }
502    bool isUpgrade()  const          { return cmd.isUpgrade(); }
503    bool isRequest() const           { return cmd.isRequest(); }
504    bool isResponse() const          { return cmd.isResponse(); }
505    bool needsWritable() const
506    {
507        // we should never check if a response needsWritable, the
508        // request has this flag, and for a response we should rather
509        // look at the hasSharers flag (if not set, the response is to
510        // be considered writable)
511        assert(isRequest());
512        return cmd.needsWritable();
513    }
514    bool needsResponse() const       { return cmd.needsResponse(); }
515    bool isInvalidate() const        { return cmd.isInvalidate(); }
516    bool isEviction() const          { return cmd.isEviction(); }
517    bool isWriteback() const         { return cmd.isWriteback(); }
518    bool hasData() const             { return cmd.hasData(); }
519    bool hasRespData() const
520    {
521        MemCmd resp_cmd = cmd.responseCommand();
522        return resp_cmd.hasData();
523    }
524    bool isLLSC() const              { return cmd.isLLSC(); }
525    bool isError() const             { return cmd.isError(); }
526    bool isPrint() const             { return cmd.isPrint(); }
527    bool isFlush() const             { return cmd.isFlush(); }
528
529    //@{
530    /// Snoop flags
531    /**
532     * Set the cacheResponding flag. This is used by the caches to
533     * signal another cache that they are responding to a request. A
534     * cache will only respond to snoops if it has the line in either
535     * Modified or Owned state. Note that on snoop hits we always pass
536     * the line as Modified and never Owned. In the case of an Owned
537     * line we proceed to invalidate all other copies.
538     *
539     * On a cache fill (see Cache::handleFill), we check hasSharers
540     * first, ignoring the cacheResponding flag if hasSharers is set.
541     * A line is consequently allocated as:
542     *
543     * hasSharers cacheResponding state
544     * true       false           Shared
545     * true       true            Shared
546     * false      false           Exclusive
547     * false      true            Modified
548     */
549    void setCacheResponding()
550    {
551        assert(isRequest());
552        assert(!flags.isSet(CACHE_RESPONDING));
553        flags.set(CACHE_RESPONDING);
554    }
555    bool cacheResponding() const { return flags.isSet(CACHE_RESPONDING); }
556    /**
557     * On fills, the hasSharers flag is used by the caches in
558     * combination with the cacheResponding flag, as clarified
559     * above. If the hasSharers flag is not set, the packet is passing
560     * writable. Thus, a response from a memory passes the line as
561     * writable by default.
562     *
563     * The hasSharers flag is also used by upstream caches to inform a
564     * downstream cache that they have the block (by calling
565     * setHasSharers on snoop request packets that hit in upstream
566     * cachs tags or MSHRs). If the snoop packet has sharers, a
567     * downstream cache is prevented from passing a dirty line upwards
568     * if it was not explicitly asked for a writable copy. See
569     * Cache::satisfyCpuSideRequest.
570     *
571     * The hasSharers flag is also used on writebacks, in
572     * combination with the WritbackClean or WritebackDirty commands,
573     * to allocate the block downstream either as:
574     *
575     * command        hasSharers state
576     * WritebackDirty false      Modified
577     * WritebackDirty true       Owned
578     * WritebackClean false      Exclusive
579     * WritebackClean true       Shared
580     */
581    void setHasSharers()    { flags.set(HAS_SHARERS); }
582    bool hasSharers() const { return flags.isSet(HAS_SHARERS); }
583    //@}
584
585    /**
586     * The express snoop flag is used for two purposes. Firstly, it is
587     * used to bypass flow control for normal (non-snoop) requests
588     * going downstream in the memory system. In cases where a cache
589     * is responding to a snoop from another cache (it had a dirty
590     * line), but the line is not writable (and there are possibly
591     * other copies), the express snoop flag is set by the downstream
592     * cache to invalidate all other copies in zero time. Secondly,
593     * the express snoop flag is also set to be able to distinguish
594     * snoop packets that came from a downstream cache, rather than
595     * snoop packets from neighbouring caches.
596     */
597    void setExpressSnoop()      { flags.set(EXPRESS_SNOOP); }
598    bool isExpressSnoop() const { return flags.isSet(EXPRESS_SNOOP); }
599
600    /**
601     * On responding to a snoop request (which only happens for
602     * Modified or Owned lines), make sure that we can transform an
603     * Owned response to a Modified one. If this flag is not set, the
604     * responding cache had the line in the Owned state, and there are
605     * possibly other Shared copies in the memory system. A downstream
606     * cache helps in orchestrating the invalidation of these copies
607     * by sending out the appropriate express snoops.
608     */
609    void setResponderHadWritable()
610    {
611        assert(cacheResponding());
612        flags.set(RESPONDER_HAD_WRITABLE);
613    }
614    bool responderHadWritable() const
615    { return flags.isSet(RESPONDER_HAD_WRITABLE); }
616
617    void setSuppressFuncError()     { flags.set(SUPPRESS_FUNC_ERROR); }
618    bool suppressFuncError() const  { return flags.isSet(SUPPRESS_FUNC_ERROR); }
619    void setBlockCached()          { flags.set(BLOCK_CACHED); }
620    bool isBlockCached() const     { return flags.isSet(BLOCK_CACHED); }
621    void clearBlockCached()        { flags.clear(BLOCK_CACHED); }
622
623    // Network error conditions... encapsulate them as methods since
624    // their encoding keeps changing (from result field to command
625    // field, etc.)
626    void
627    setBadAddress()
628    {
629        assert(isResponse());
630        cmd = MemCmd::BadAddressError;
631    }
632
633    void copyError(Packet *pkt) { assert(pkt->isError()); cmd = pkt->cmd; }
634
635    Addr getAddr() const { assert(flags.isSet(VALID_ADDR)); return addr; }
636    /**
637     * Update the address of this packet mid-transaction. This is used
638     * by the address mapper to change an already set address to a new
639     * one based on the system configuration. It is intended to remap
640     * an existing address, so it asserts that the current address is
641     * valid.
642     */
643    void setAddr(Addr _addr) { assert(flags.isSet(VALID_ADDR)); addr = _addr; }
644
645    unsigned getSize() const  { assert(flags.isSet(VALID_SIZE)); return size; }
646
647    Addr getOffset(unsigned int blk_size) const
648    {
649        return getAddr() & Addr(blk_size - 1);
650    }
651
652    Addr getBlockAddr(unsigned int blk_size) const
653    {
654        return getAddr() & ~(Addr(blk_size - 1));
655    }
656
657    bool isSecure() const
658    {
659        assert(flags.isSet(VALID_ADDR));
660        return _isSecure;
661    }
662
663    /**
664     * It has been determined that the SC packet should successfully update
665     * memory. Therefore, convert this SC packet to a normal write.
666     */
667    void
668    convertScToWrite()
669    {
670        assert(isLLSC());
671        assert(isWrite());
672        cmd = MemCmd::WriteReq;
673    }
674
675    /**
676     * When ruby is in use, Ruby will monitor the cache line and the
677     * phys memory should treat LL ops as normal reads.
678     */
679    void
680    convertLlToRead()
681    {
682        assert(isLLSC());
683        assert(isRead());
684        cmd = MemCmd::ReadReq;
685    }
686
687    /**
688     * Constructor. Note that a Request object must be constructed
689     * first, but the Requests's physical address and size fields need
690     * not be valid. The command must be supplied.
691     */
692    Packet(const RequestPtr _req, MemCmd _cmd)
693        :  cmd(_cmd), req(_req), data(nullptr), addr(0), _isSecure(false),
694           size(0), headerDelay(0), snoopDelay(0), payloadDelay(0),
695           senderState(NULL)
696    {
697        if (req->hasPaddr()) {
698            addr = req->getPaddr();
699            flags.set(VALID_ADDR);
700            _isSecure = req->isSecure();
701        }
702        if (req->hasSize()) {
703            size = req->getSize();
704            flags.set(VALID_SIZE);
705        }
706    }
707
708    /**
709     * Alternate constructor if you are trying to create a packet with
710     * a request that is for a whole block, not the address from the
711     * req.  this allows for overriding the size/addr of the req.
712     */
713    Packet(const RequestPtr _req, MemCmd _cmd, int _blkSize)
714        :  cmd(_cmd), req(_req), data(nullptr), addr(0), _isSecure(false),
715           headerDelay(0), snoopDelay(0), payloadDelay(0),
716           senderState(NULL)
717    {
718        if (req->hasPaddr()) {
719            addr = req->getPaddr() & ~(_blkSize - 1);
720            flags.set(VALID_ADDR);
721            _isSecure = req->isSecure();
722        }
723        size = _blkSize;
724        flags.set(VALID_SIZE);
725    }
726
727    /**
728     * Alternate constructor for copying a packet.  Copy all fields
729     * *except* if the original packet's data was dynamic, don't copy
730     * that, as we can't guarantee that the new packet's lifetime is
731     * less than that of the original packet.  In this case the new
732     * packet should allocate its own data.
733     */
734    Packet(const PacketPtr pkt, bool clear_flags, bool alloc_data)
735        :  cmd(pkt->cmd), req(pkt->req),
736           data(nullptr),
737           addr(pkt->addr), _isSecure(pkt->_isSecure), size(pkt->size),
738           bytesValid(pkt->bytesValid),
739           headerDelay(pkt->headerDelay),
740           snoopDelay(0),
741           payloadDelay(pkt->payloadDelay),
742           senderState(pkt->senderState)
743    {
744        if (!clear_flags)
745            flags.set(pkt->flags & COPY_FLAGS);
746
747        flags.set(pkt->flags & (VALID_ADDR|VALID_SIZE));
748
749        // should we allocate space for data, or not, the express
750        // snoops do not need to carry any data as they only serve to
751        // co-ordinate state changes
752        if (alloc_data) {
753            // even if asked to allocate data, if the original packet
754            // holds static data, then the sender will not be doing
755            // any memcpy on receiving the response, thus we simply
756            // carry the pointer forward
757            if (pkt->flags.isSet(STATIC_DATA)) {
758                data = pkt->data;
759                flags.set(STATIC_DATA);
760            } else {
761                allocate();
762            }
763        }
764    }
765
766    /**
767     * Generate the appropriate read MemCmd based on the Request flags.
768     */
769    static MemCmd
770    makeReadCmd(const RequestPtr req)
771    {
772        if (req->isLLSC())
773            return MemCmd::LoadLockedReq;
774        else if (req->isPrefetch())
775            return MemCmd::SoftPFReq;
776        else
777            return MemCmd::ReadReq;
778    }
779
780    /**
781     * Generate the appropriate write MemCmd based on the Request flags.
782     */
783    static MemCmd
784    makeWriteCmd(const RequestPtr req)
785    {
786        if (req->isLLSC())
787            return MemCmd::StoreCondReq;
788        else if (req->isSwap())
789            return MemCmd::SwapReq;
790        else
791            return MemCmd::WriteReq;
792    }
793
794    /**
795     * Constructor-like methods that return Packets based on Request objects.
796     * Fine-tune the MemCmd type if it's not a vanilla read or write.
797     */
798    static PacketPtr
799    createRead(const RequestPtr req)
800    {
801        return new Packet(req, makeReadCmd(req));
802    }
803
804    static PacketPtr
805    createWrite(const RequestPtr req)
806    {
807        return new Packet(req, makeWriteCmd(req));
808    }
809
810    /**
811     * clean up packet variables
812     */
813    ~Packet()
814    {
815        // Delete the request object if this is a request packet which
816        // does not need a response, because the requester will not get
817        // a chance. If the request packet needs a response then the
818        // request will be deleted on receipt of the response
819        // packet. We also make sure to never delete the request for
820        // express snoops, even for cases when responses are not
821        // needed (CleanEvict and Writeback), since the snoop packet
822        // re-uses the same request.
823        if (req && isRequest() && !needsResponse() &&
824            !isExpressSnoop()) {
825            delete req;
826        }
827        deleteData();
828    }
829
830    /**
831     * Take a request packet and modify it in place to be suitable for
832     * returning as a response to that request.
833     */
834    void
835    makeResponse()
836    {
837        assert(needsResponse());
838        assert(isRequest());
839        cmd = cmd.responseCommand();
840
841        // responses are never express, even if the snoop that
842        // triggered them was
843        flags.clear(EXPRESS_SNOOP);
844    }
845
846    void
847    makeAtomicResponse()
848    {
849        makeResponse();
850    }
851
852    void
853    makeTimingResponse()
854    {
855        makeResponse();
856    }
857
858    void
859    setFunctionalResponseStatus(bool success)
860    {
861        if (!success) {
862            if (isWrite()) {
863                cmd = MemCmd::FunctionalWriteError;
864            } else {
865                cmd = MemCmd::FunctionalReadError;
866            }
867        }
868    }
869
870    void
871    setSize(unsigned size)
872    {
873        assert(!flags.isSet(VALID_SIZE));
874
875        this->size = size;
876        flags.set(VALID_SIZE);
877    }
878
879
880  public:
881    /**
882     * @{
883     * @name Data accessor mehtods
884     */
885
886    /**
887     * Set the data pointer to the following value that should not be
888     * freed. Static data allows us to do a single memcpy even if
889     * multiple packets are required to get from source to destination
890     * and back. In essence the pointer is set calling dataStatic on
891     * the original packet, and whenever this packet is copied and
892     * forwarded the same pointer is passed on. When a packet
893     * eventually reaches the destination holding the data, it is
894     * copied once into the location originally set. On the way back
895     * to the source, no copies are necessary.
896     */
897    template <typename T>
898    void
899    dataStatic(T *p)
900    {
901        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
902        data = (PacketDataPtr)p;
903        flags.set(STATIC_DATA);
904    }
905
906    /**
907     * Set the data pointer to the following value that should not be
908     * freed. This version of the function allows the pointer passed
909     * to us to be const. To avoid issues down the line we cast the
910     * constness away, the alternative would be to keep both a const
911     * and non-const data pointer and cleverly choose between
912     * them. Note that this is only allowed for static data.
913     */
914    template <typename T>
915    void
916    dataStaticConst(const T *p)
917    {
918        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
919        data = const_cast<PacketDataPtr>(p);
920        flags.set(STATIC_DATA);
921    }
922
923    /**
924     * Set the data pointer to a value that should have delete []
925     * called on it. Dynamic data is local to this packet, and as the
926     * packet travels from source to destination, forwarded packets
927     * will allocate their own data. When a packet reaches the final
928     * destination it will populate the dynamic data of that specific
929     * packet, and on the way back towards the source, memcpy will be
930     * invoked in every step where a new packet was created e.g. in
931     * the caches. Ultimately when the response reaches the source a
932     * final memcpy is needed to extract the data from the packet
933     * before it is deallocated.
934     */
935    template <typename T>
936    void
937    dataDynamic(T *p)
938    {
939        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
940        data = (PacketDataPtr)p;
941        flags.set(DYNAMIC_DATA);
942    }
943
944    /**
945     * get a pointer to the data ptr.
946     */
947    template <typename T>
948    T*
949    getPtr()
950    {
951        assert(flags.isSet(STATIC_DATA|DYNAMIC_DATA));
952        return (T*)data;
953    }
954
955    template <typename T>
956    const T*
957    getConstPtr() const
958    {
959        assert(flags.isSet(STATIC_DATA|DYNAMIC_DATA));
960        return (const T*)data;
961    }
962
963    /**
964     * Get the data in the packet byte swapped from big endian to
965     * host endian.
966     */
967    template <typename T>
968    T getBE() const;
969
970    /**
971     * Get the data in the packet byte swapped from little endian to
972     * host endian.
973     */
974    template <typename T>
975    T getLE() const;
976
977    /**
978     * Get the data in the packet byte swapped from the specified
979     * endianness.
980     */
981    template <typename T>
982    T get(ByteOrder endian) const;
983
984    /**
985     * Get the data in the packet byte swapped from guest to host
986     * endian.
987     */
988    template <typename T>
989    T get() const;
990
991    /** Set the value in the data pointer to v as big endian. */
992    template <typename T>
993    void setBE(T v);
994
995    /** Set the value in the data pointer to v as little endian. */
996    template <typename T>
997    void setLE(T v);
998
999    /**
1000     * Set the value in the data pointer to v using the specified
1001     * endianness.
1002     */
1003    template <typename T>
1004    void set(T v, ByteOrder endian);
1005
1006    /** Set the value in the data pointer to v as guest endian. */
1007    template <typename T>
1008    void set(T v);
1009
1010    /**
1011     * Copy data into the packet from the provided pointer.
1012     */
1013    void
1014    setData(const uint8_t *p)
1015    {
1016        // we should never be copying data onto itself, which means we
1017        // must idenfity packets with static data, as they carry the
1018        // same pointer from source to destination and back
1019        assert(p != getPtr<uint8_t>() || flags.isSet(STATIC_DATA));
1020
1021        if (p != getPtr<uint8_t>())
1022            // for packet with allocated dynamic data, we copy data from
1023            // one to the other, e.g. a forwarded response to a response
1024            std::memcpy(getPtr<uint8_t>(), p, getSize());
1025    }
1026
1027    /**
1028     * Copy data into the packet from the provided block pointer,
1029     * which is aligned to the given block size.
1030     */
1031    void
1032    setDataFromBlock(const uint8_t *blk_data, int blkSize)
1033    {
1034        setData(blk_data + getOffset(blkSize));
1035    }
1036
1037    /**
1038     * Copy data from the packet to the provided block pointer, which
1039     * is aligned to the given block size.
1040     */
1041    void
1042    writeData(uint8_t *p) const
1043    {
1044        std::memcpy(p, getConstPtr<uint8_t>(), getSize());
1045    }
1046
1047    /**
1048     * Copy data from the packet to the memory at the provided pointer.
1049     */
1050    void
1051    writeDataToBlock(uint8_t *blk_data, int blkSize) const
1052    {
1053        writeData(blk_data + getOffset(blkSize));
1054    }
1055
1056    /**
1057     * delete the data pointed to in the data pointer. Ok to call to
1058     * matter how data was allocted.
1059     */
1060    void
1061    deleteData()
1062    {
1063        if (flags.isSet(DYNAMIC_DATA))
1064            delete [] data;
1065
1066        flags.clear(STATIC_DATA|DYNAMIC_DATA);
1067        data = NULL;
1068    }
1069
1070    /** Allocate memory for the packet. */
1071    void
1072    allocate()
1073    {
1074        // if either this command or the response command has a data
1075        // payload, actually allocate space
1076        if (hasData() || hasRespData()) {
1077            assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
1078            flags.set(DYNAMIC_DATA);
1079            data = new uint8_t[getSize()];
1080        }
1081    }
1082
1083    /** @} */
1084
1085  private: // Private data accessor methods
1086    /** Get the data in the packet without byte swapping. */
1087    template <typename T>
1088    T getRaw() const;
1089
1090    /** Set the value in the data pointer to v without byte swapping. */
1091    template <typename T>
1092    void setRaw(T v);
1093
1094  public:
1095    /**
1096     * Check a functional request against a memory value stored in
1097     * another packet (i.e. an in-transit request or
1098     * response). Returns true if the current packet is a read, and
1099     * the other packet provides the data, which is then copied to the
1100     * current packet. If the current packet is a write, and the other
1101     * packet intersects this one, then we update the data
1102     * accordingly.
1103     */
1104    bool
1105    checkFunctional(PacketPtr other)
1106    {
1107        // all packets that are carrying a payload should have a valid
1108        // data pointer
1109        return checkFunctional(other, other->getAddr(), other->isSecure(),
1110                               other->getSize(),
1111                               other->hasData() ?
1112                               other->getPtr<uint8_t>() : NULL);
1113    }
1114
1115    /**
1116     * Does the request need to check for cached copies of the same block
1117     * in the memory hierarchy above.
1118     **/
1119    bool
1120    mustCheckAbove() const
1121    {
1122        return cmd == MemCmd::HardPFReq || isEviction();
1123    }
1124
1125    /**
1126     * Is this packet a clean eviction, including both actual clean
1127     * evict packets, but also clean writebacks.
1128     */
1129    bool
1130    isCleanEviction() const
1131    {
1132        return cmd == MemCmd::CleanEvict || cmd == MemCmd::WritebackClean;
1133    }
1134
1135    /**
1136     * Check a functional request against a memory value represented
1137     * by a base/size pair and an associated data array. If the
1138     * current packet is a read, it may be satisfied by the memory
1139     * value. If the current packet is a write, it may update the
1140     * memory value.
1141     */
1142    bool
1143    checkFunctional(Printable *obj, Addr base, bool is_secure, int size,
1144                    uint8_t *_data);
1145
1146    /**
1147     * Push label for PrintReq (safe to call unconditionally).
1148     */
1149    void
1150    pushLabel(const std::string &lbl)
1151    {
1152        if (isPrint())
1153            safe_cast<PrintReqState*>(senderState)->pushLabel(lbl);
1154    }
1155
1156    /**
1157     * Pop label for PrintReq (safe to call unconditionally).
1158     */
1159    void
1160    popLabel()
1161    {
1162        if (isPrint())
1163            safe_cast<PrintReqState*>(senderState)->popLabel();
1164    }
1165
1166    void print(std::ostream &o, int verbosity = 0,
1167               const std::string &prefix = "") const;
1168
1169    /**
1170     * A no-args wrapper of print(std::ostream...)
1171     * meant to be invoked from DPRINTFs
1172     * avoiding string overheads in fast mode
1173     * @return string with the request's type and start<->end addresses
1174     */
1175    std::string print() const;
1176};
1177
1178#endif //__MEM_PACKET_HH
1179