packet.hh revision 10572:fc4c90a7d2f5
1/*
2 * Copyright (c) 2012-2014 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 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        Writeback,
90        SoftPFReq,
91        HardPFReq,
92        SoftPFResp,
93        HardPFResp,
94        WriteInvalidateReq,
95        WriteInvalidateResp,
96        UpgradeReq,
97        SCUpgradeReq,           // Special "weak" upgrade for StoreCond
98        UpgradeResp,
99        SCUpgradeFailReq,       // Failed SCUpgradeReq in MSHR (never sent)
100        UpgradeFailResp,        // Valid for SCUpgradeReq only
101        ReadExReq,
102        ReadExResp,
103        LoadLockedReq,
104        StoreCondReq,
105        StoreCondFailReq,       // Failed StoreCondReq in MSHR (never sent)
106        StoreCondResp,
107        SwapReq,
108        SwapResp,
109        MessageReq,
110        MessageResp,
111        // Error responses
112        // @TODO these should be classified as responses rather than
113        // requests; coding them as requests initially for backwards
114        // compatibility
115        InvalidDestError,  // packet dest field invalid
116        BadAddressError,   // memory address invalid
117        FunctionalReadError, // unable to fulfill functional read
118        FunctionalWriteError, // unable to fulfill functional write
119        // Fake simulator-only commands
120        PrintReq,       // Print state matching address
121        FlushReq,      //request for a cache flush
122        InvalidationReq,   // request for address to be invalidated from lsq
123        NUM_MEM_CMDS
124    };
125
126  private:
127    /**
128     * List of command attributes.
129     */
130    enum Attribute
131    {
132        IsRead,         //!< Data flows from responder to requester
133        IsWrite,        //!< Data flows from requester to responder
134        IsUpgrade,
135        IsInvalidate,
136        NeedsExclusive, //!< Requires exclusive copy to complete in-cache
137        IsRequest,      //!< Issued by requester
138        IsResponse,     //!< Issue by responder
139        NeedsResponse,  //!< Requester needs response from target
140        IsSWPrefetch,
141        IsHWPrefetch,
142        IsLlsc,         //!< Alpha/MIPS LL or SC access
143        HasData,        //!< There is an associated payload
144        IsError,        //!< Error response
145        IsPrint,        //!< Print state matching address (for debugging)
146        IsFlush,        //!< Flush the address from caches
147        NUM_COMMAND_ATTRIBUTES
148    };
149
150    /**
151     * Structure that defines attributes and other data associated
152     * with a Command.
153     */
154    struct CommandInfo
155    {
156        /// Set of attribute flags.
157        const std::bitset<NUM_COMMAND_ATTRIBUTES> attributes;
158        /// Corresponding response for requests; InvalidCmd if no
159        /// response is applicable.
160        const Command response;
161        /// String representation (for printing)
162        const std::string str;
163    };
164
165    /// Array to map Command enum to associated info.
166    static const CommandInfo commandInfo[];
167
168  private:
169
170    Command cmd;
171
172    bool
173    testCmdAttrib(MemCmd::Attribute attrib) const
174    {
175        return commandInfo[cmd].attributes[attrib] != 0;
176    }
177
178  public:
179
180    bool isRead() const         { return testCmdAttrib(IsRead); }
181    bool isWrite() const        { return testCmdAttrib(IsWrite); }
182    bool isUpgrade() const      { return testCmdAttrib(IsUpgrade); }
183    bool isRequest() const      { return testCmdAttrib(IsRequest); }
184    bool isResponse() const     { return testCmdAttrib(IsResponse); }
185    bool needsExclusive() const { return testCmdAttrib(NeedsExclusive); }
186    bool needsResponse() const  { return testCmdAttrib(NeedsResponse); }
187    bool isInvalidate() const   { return testCmdAttrib(IsInvalidate); }
188
189    /**
190     * Check if this particular packet type carries payload data. Note
191     * that this does not reflect if the data pointer of the packet is
192     * valid or not.
193     */
194    bool hasData() const        { return testCmdAttrib(HasData); }
195    bool isLLSC() const         { return testCmdAttrib(IsLlsc); }
196    bool isSWPrefetch() const   { return testCmdAttrib(IsSWPrefetch); }
197    bool isHWPrefetch() const   { return testCmdAttrib(IsHWPrefetch); }
198    bool isPrefetch() const     { return testCmdAttrib(IsSWPrefetch) ||
199                                         testCmdAttrib(IsHWPrefetch); }
200    bool isError() const        { return testCmdAttrib(IsError); }
201    bool isPrint() const        { return testCmdAttrib(IsPrint); }
202    bool isFlush() const        { return testCmdAttrib(IsFlush); }
203
204    const Command
205    responseCommand() const
206    {
207        return commandInfo[cmd].response;
208    }
209
210    /// Return the string to a cmd given by idx.
211    const std::string &toString() const { return commandInfo[cmd].str; }
212    int toInt() const { return (int)cmd; }
213
214    MemCmd(Command _cmd) : cmd(_cmd) { }
215    MemCmd(int _cmd) : cmd((Command)_cmd) { }
216    MemCmd() : cmd(InvalidCmd) { }
217
218    bool operator==(MemCmd c2) const { return (cmd == c2.cmd); }
219    bool operator!=(MemCmd c2) const { return (cmd != c2.cmd); }
220};
221
222/**
223 * A Packet is used to encapsulate a transfer between two objects in
224 * the memory system (e.g., the L1 and L2 cache).  (In contrast, a
225 * single Request travels all the way from the requester to the
226 * ultimate destination and back, possibly being conveyed by several
227 * different Packets along the way.)
228 */
229class Packet : public Printable
230{
231  public:
232    typedef uint32_t FlagsType;
233    typedef ::Flags<FlagsType> Flags;
234
235  private:
236    static const FlagsType PUBLIC_FLAGS           = 0x00000000;
237    static const FlagsType PRIVATE_FLAGS          = 0x00007F0F;
238    static const FlagsType COPY_FLAGS             = 0x0000000F;
239
240    static const FlagsType SHARED                 = 0x00000001;
241    // Special control flags
242    /// Special timing-mode atomic snoop for multi-level coherence.
243    static const FlagsType EXPRESS_SNOOP          = 0x00000002;
244    /// Does supplier have exclusive copy?
245    /// Useful for multi-level coherence.
246    static const FlagsType SUPPLY_EXCLUSIVE       = 0x00000004;
247    // Snoop response flags
248    static const FlagsType MEM_INHIBIT            = 0x00000008;
249    /// Are the 'addr' and 'size' fields valid?
250    static const FlagsType VALID_ADDR             = 0x00000100;
251    static const FlagsType VALID_SIZE             = 0x00000200;
252    /// Is the data pointer set to a value that shouldn't be freed
253    /// when the packet is destroyed?
254    static const FlagsType STATIC_DATA            = 0x00001000;
255    /// The data pointer points to a value that should be freed when
256    /// the packet is destroyed. The pointer is assumed to be pointing
257    /// to an array, and delete [] is consequently called
258    static const FlagsType DYNAMIC_DATA           = 0x00002000;
259    /// suppress the error if this packet encounters a functional
260    /// access failure.
261    static const FlagsType SUPPRESS_FUNC_ERROR    = 0x00008000;
262    // Signal prefetch squash through express snoop flag
263    static const FlagsType PREFETCH_SNOOP_SQUASH  = 0x00010000;
264
265    Flags flags;
266
267  public:
268    typedef MemCmd::Command Command;
269
270    /// The command field of the packet.
271    MemCmd cmd;
272
273    /// A pointer to the original request.
274    const RequestPtr req;
275
276  private:
277   /**
278    * A pointer to the data being transfered.  It can be differnt
279    * sizes at each level of the heirarchy so it belongs in the
280    * packet, not request. This may or may not be populated when a
281    * responder recieves the packet. If not populated it memory should
282    * be allocated.
283    */
284    PacketDataPtr data;
285
286    /// The address of the request.  This address could be virtual or
287    /// physical, depending on the system configuration.
288    Addr addr;
289
290    /// True if the request targets the secure memory space.
291    bool _isSecure;
292
293    /// The size of the request or transfer.
294    unsigned size;
295
296    /**
297     * Source port identifier set on a request packet to enable
298     * appropriate routing of the responses. The source port
299     * identifier is set by any multiplexing component, e.g. a
300     * crossbar, as the timing responses need this information to be
301     * routed back to the appropriate port at a later point in
302     * time. The field can be updated (over-written) as the request
303     * packet passes through additional multiplexing components, and
304     * it is their responsibility to remember the original source port
305     * identifier, for example by using an appropriate sender
306     * state. The latter is done in the cache and bridge.
307     */
308    PortID src;
309
310    /**
311     * Destination port identifier that is present on all response
312     * packets that passed through a multiplexing component as a
313     * request packet. The source port identifier is turned into a
314     * destination port identifier when the packet is turned into a
315     * response, and the destination is used, e.g. by the crossbar, to
316     * select the appropriate path through the interconnect.
317     */
318    PortID dest;
319
320    /**
321     * The original value of the command field.  Only valid when the
322     * current command field is an error condition; in that case, the
323     * previous contents of the command field are copied here.  This
324     * field is *not* set on non-error responses.
325     */
326    MemCmd origCmd;
327
328    /**
329     * These values specify the range of bytes found that satisfy a
330     * functional read.
331     */
332    uint16_t bytesValidStart;
333    uint16_t bytesValidEnd;
334
335  public:
336
337    /**
338     * The extra delay from seeing the packet until the first word is
339     * transmitted. This delay is used to communicate the crossbar
340     * forwarding latency to the neighbouring object (e.g. a cache)
341     * that actually makes the packet wait. As the delay is relative,
342     * a 32-bit unsigned should be sufficient.
343     */
344    uint32_t firstWordDelay;
345
346    /**
347     * The extra pipelining delay from seeing the packet until the
348     * last word is transmitted by the component that provided it (if
349     * any). This includes the first word delay. Similar to the first
350     * word delay, this is used to make up for the fact that the
351     * crossbar does not make the packet wait. As the delay is
352     * relative, a 32-bit unsigned should be sufficient.
353     */
354    uint32_t lastWordDelay;
355
356    /**
357     * A virtual base opaque structure used to hold state associated
358     * with the packet (e.g., an MSHR), specific to a MemObject that
359     * sees the packet. A pointer to this state is returned in the
360     * packet's response so that the MemObject in question can quickly
361     * look up the state needed to process it. A specific subclass
362     * would be derived from this to carry state specific to a
363     * particular sending device.
364     *
365     * As multiple MemObjects may add their SenderState throughout the
366     * memory system, the SenderStates create a stack, where a
367     * MemObject can add a new Senderstate, as long as the
368     * predecessing SenderState is restored when the response comes
369     * back. For this reason, the predecessor should always be
370     * populated with the current SenderState of a packet before
371     * modifying the senderState field in the request packet.
372     */
373    struct SenderState
374    {
375        SenderState* predecessor;
376        SenderState() : predecessor(NULL) {}
377        virtual ~SenderState() {}
378    };
379
380    /**
381     * Object used to maintain state of a PrintReq.  The senderState
382     * field of a PrintReq should always be of this type.
383     */
384    class PrintReqState : public SenderState
385    {
386      private:
387        /**
388         * An entry in the label stack.
389         */
390        struct LabelStackEntry
391        {
392            const std::string label;
393            std::string *prefix;
394            bool labelPrinted;
395            LabelStackEntry(const std::string &_label, std::string *_prefix);
396        };
397
398        typedef std::list<LabelStackEntry> LabelStack;
399        LabelStack labelStack;
400
401        std::string *curPrefixPtr;
402
403      public:
404        std::ostream &os;
405        const int verbosity;
406
407        PrintReqState(std::ostream &os, int verbosity = 0);
408        ~PrintReqState();
409
410        /**
411         * Returns the current line prefix.
412         */
413        const std::string &curPrefix() { return *curPrefixPtr; }
414
415        /**
416         * Push a label onto the label stack, and prepend the given
417         * prefix string onto the current prefix.  Labels will only be
418         * printed if an object within the label's scope is printed.
419         */
420        void pushLabel(const std::string &lbl,
421                       const std::string &prefix = "  ");
422
423        /**
424         * Pop a label off the label stack.
425         */
426        void popLabel();
427
428        /**
429         * Print all of the pending unprinted labels on the
430         * stack. Called by printObj(), so normally not called by
431         * users unless bypassing printObj().
432         */
433        void printLabels();
434
435        /**
436         * Print a Printable object to os, because it matched the
437         * address on a PrintReq.
438         */
439        void printObj(Printable *obj);
440    };
441
442    /**
443     * This packet's sender state.  Devices should use dynamic_cast<>
444     * to cast to the state appropriate to the sender.  The intent of
445     * this variable is to allow a device to attach extra information
446     * to a request. A response packet must return the sender state
447     * that was attached to the original request (even if a new packet
448     * is created).
449     */
450    SenderState *senderState;
451
452    /**
453     * Push a new sender state to the packet and make the current
454     * sender state the predecessor of the new one. This should be
455     * prefered over direct manipulation of the senderState member
456     * variable.
457     *
458     * @param sender_state SenderState to push at the top of the stack
459     */
460    void pushSenderState(SenderState *sender_state);
461
462    /**
463     * Pop the top of the state stack and return a pointer to it. This
464     * assumes the current sender state is not NULL. This should be
465     * preferred over direct manipulation of the senderState member
466     * variable.
467     *
468     * @return The current top of the stack
469     */
470    SenderState *popSenderState();
471
472    /**
473     * Go through the sender state stack and return the first instance
474     * that is of type T (as determined by a dynamic_cast). If there
475     * is no sender state of type T, NULL is returned.
476     *
477     * @return The topmost state of type T
478     */
479    template <typename T>
480    T * findNextSenderState() const
481    {
482        T *t = NULL;
483        SenderState* sender_state = senderState;
484        while (t == NULL && sender_state != NULL) {
485            t = dynamic_cast<T*>(sender_state);
486            sender_state = sender_state->predecessor;
487        }
488        return t;
489    }
490
491    /// Return the string name of the cmd field (for debugging and
492    /// tracing).
493    const std::string &cmdString() const { return cmd.toString(); }
494
495    /// Return the index of this command.
496    inline int cmdToIndex() const { return cmd.toInt(); }
497
498    bool isRead() const         { return cmd.isRead(); }
499    bool isWrite() const        { return cmd.isWrite(); }
500    bool isUpgrade()  const     { return cmd.isUpgrade(); }
501    bool isRequest() const      { return cmd.isRequest(); }
502    bool isResponse() const     { return cmd.isResponse(); }
503    bool needsExclusive() const { return cmd.needsExclusive(); }
504    bool needsResponse() const  { return cmd.needsResponse(); }
505    bool isInvalidate() const   { return cmd.isInvalidate(); }
506    bool hasData() const        { return cmd.hasData(); }
507    bool isLLSC() const         { return cmd.isLLSC(); }
508    bool isError() const        { return cmd.isError(); }
509    bool isPrint() const        { return cmd.isPrint(); }
510    bool isFlush() const        { return cmd.isFlush(); }
511
512    // Snoop flags
513    void assertMemInhibit()
514    {
515        assert(isRequest());
516        assert(!flags.isSet(MEM_INHIBIT));
517        flags.set(MEM_INHIBIT);
518    }
519    bool memInhibitAsserted() const { return flags.isSet(MEM_INHIBIT); }
520    void assertShared()             { flags.set(SHARED); }
521    bool sharedAsserted() const     { return flags.isSet(SHARED); }
522
523    // Special control flags
524    void setExpressSnoop()          { flags.set(EXPRESS_SNOOP); }
525    bool isExpressSnoop() const     { return flags.isSet(EXPRESS_SNOOP); }
526    void setSupplyExclusive()       { flags.set(SUPPLY_EXCLUSIVE); }
527    void clearSupplyExclusive()     { flags.clear(SUPPLY_EXCLUSIVE); }
528    bool isSupplyExclusive() const  { return flags.isSet(SUPPLY_EXCLUSIVE); }
529    void setSuppressFuncError()     { flags.set(SUPPRESS_FUNC_ERROR); }
530    bool suppressFuncError() const  { return flags.isSet(SUPPRESS_FUNC_ERROR); }
531    void setPrefetchSquashed()      { flags.set(PREFETCH_SNOOP_SQUASH); }
532    bool prefetchSquashed() const   { return flags.isSet(PREFETCH_SNOOP_SQUASH); }
533
534    // Network error conditions... encapsulate them as methods since
535    // their encoding keeps changing (from result field to command
536    // field, etc.)
537    void
538    setBadAddress()
539    {
540        assert(isResponse());
541        cmd = MemCmd::BadAddressError;
542    }
543
544    bool hadBadAddress() const { return cmd == MemCmd::BadAddressError; }
545    void copyError(Packet *pkt) { assert(pkt->isError()); cmd = pkt->cmd; }
546
547    /// Accessor function to get the source index of the packet.
548    PortID getSrc() const { return src; }
549    /// Accessor function to set the source index of the packet.
550    void setSrc(PortID _src) { src = _src; }
551
552    /// Accessor function for the destination index of the packet.
553    PortID getDest() const { return dest; }
554    /// Accessor function to set the destination index of the packet.
555    void setDest(PortID _dest) { dest = _dest; }
556    /// Reset destination field, e.g. to turn a response into a request again.
557    void clearDest() { dest = InvalidPortID; }
558
559    Addr getAddr() const { assert(flags.isSet(VALID_ADDR)); return addr; }
560    /**
561     * Update the address of this packet mid-transaction. This is used
562     * by the address mapper to change an already set address to a new
563     * one based on the system configuration. It is intended to remap
564     * an existing address, so it asserts that the current address is
565     * valid.
566     */
567    void setAddr(Addr _addr) { assert(flags.isSet(VALID_ADDR)); addr = _addr; }
568
569    unsigned getSize() const  { assert(flags.isSet(VALID_SIZE)); return size; }
570    Addr getOffset(int blkSize) const { return getAddr() & (Addr)(blkSize - 1); }
571
572    bool isSecure() const
573    {
574        assert(flags.isSet(VALID_ADDR));
575        return _isSecure;
576    }
577
578    /**
579     * It has been determined that the SC packet should successfully update
580     * memory.  Therefore, convert this SC packet to a normal write.
581     */
582    void
583    convertScToWrite()
584    {
585        assert(isLLSC());
586        assert(isWrite());
587        cmd = MemCmd::WriteReq;
588    }
589
590    /**
591     * When ruby is in use, Ruby will monitor the cache line and thus M5
592     * phys memory should treat LL ops as normal reads.
593     */
594    void
595    convertLlToRead()
596    {
597        assert(isLLSC());
598        assert(isRead());
599        cmd = MemCmd::ReadReq;
600    }
601
602    /**
603     * Constructor.  Note that a Request object must be constructed
604     * first, but the Requests's physical address and size fields need
605     * not be valid. The command must be supplied.
606     */
607    Packet(const RequestPtr _req, MemCmd _cmd)
608        :  cmd(_cmd), req(_req), data(nullptr), addr(0), _isSecure(false),
609           size(0), src(InvalidPortID), dest(InvalidPortID),
610           bytesValidStart(0), bytesValidEnd(0),
611           firstWordDelay(0), lastWordDelay(0),
612           senderState(NULL)
613    {
614        if (req->hasPaddr()) {
615            addr = req->getPaddr();
616            flags.set(VALID_ADDR);
617            _isSecure = req->isSecure();
618        }
619        if (req->hasSize()) {
620            size = req->getSize();
621            flags.set(VALID_SIZE);
622        }
623    }
624
625    /**
626     * Alternate constructor if you are trying to create a packet with
627     * a request that is for a whole block, not the address from the
628     * req.  this allows for overriding the size/addr of the req.
629     */
630    Packet(const RequestPtr _req, MemCmd _cmd, int _blkSize)
631        :  cmd(_cmd), req(_req), data(nullptr), addr(0), _isSecure(false),
632           src(InvalidPortID), dest(InvalidPortID),
633           bytesValidStart(0), bytesValidEnd(0),
634           firstWordDelay(0), lastWordDelay(0),
635           senderState(NULL)
636    {
637        if (req->hasPaddr()) {
638            addr = req->getPaddr() & ~(_blkSize - 1);
639            flags.set(VALID_ADDR);
640            _isSecure = req->isSecure();
641        }
642        size = _blkSize;
643        flags.set(VALID_SIZE);
644    }
645
646    /**
647     * Alternate constructor for copying a packet.  Copy all fields
648     * *except* if the original packet's data was dynamic, don't copy
649     * that, as we can't guarantee that the new packet's lifetime is
650     * less than that of the original packet.  In this case the new
651     * packet should allocate its own data.
652     */
653    Packet(PacketPtr pkt, bool clear_flags, bool alloc_data)
654        :  cmd(pkt->cmd), req(pkt->req),
655           data(nullptr),
656           addr(pkt->addr), _isSecure(pkt->_isSecure), size(pkt->size),
657           src(pkt->src), dest(pkt->dest),
658           bytesValidStart(pkt->bytesValidStart),
659           bytesValidEnd(pkt->bytesValidEnd),
660           firstWordDelay(pkt->firstWordDelay),
661           lastWordDelay(pkt->lastWordDelay),
662           senderState(pkt->senderState)
663    {
664        if (!clear_flags)
665            flags.set(pkt->flags & COPY_FLAGS);
666
667        flags.set(pkt->flags & (VALID_ADDR|VALID_SIZE));
668
669        // should we allocate space for data, or not, the express
670        // snoops do not need to carry any data as they only serve to
671        // co-ordinate state changes
672        if (alloc_data) {
673            // even if asked to allocate data, if the original packet
674            // holds static data, then the sender will not be doing
675            // any memcpy on receiving the response, thus we simply
676            // carry the pointer forward
677            if (pkt->flags.isSet(STATIC_DATA)) {
678                data = pkt->data;
679                flags.set(STATIC_DATA);
680            } else {
681                allocate();
682            }
683        }
684    }
685
686    /**
687     * Change the packet type based on request type.
688     */
689    void
690    refineCommand()
691    {
692        if (cmd == MemCmd::ReadReq) {
693            if (req->isLLSC()) {
694                cmd = MemCmd::LoadLockedReq;
695            } else if (req->isPrefetch()) {
696                cmd = MemCmd::SoftPFReq;
697            }
698        } else if (cmd == MemCmd::WriteReq) {
699            if (req->isLLSC()) {
700                cmd = MemCmd::StoreCondReq;
701            } else if (req->isSwap()) {
702                cmd = MemCmd::SwapReq;
703            }
704        }
705    }
706
707    /**
708     * Constructor-like methods that return Packets based on Request objects.
709     * Will call refineCommand() to fine-tune the Packet type if it's not a
710     * vanilla read or write.
711     */
712    static PacketPtr
713    createRead(const RequestPtr req)
714    {
715        PacketPtr pkt = new Packet(req, MemCmd::ReadReq);
716        pkt->refineCommand();
717        return pkt;
718    }
719
720    static PacketPtr
721    createWrite(const RequestPtr req)
722    {
723        PacketPtr pkt = new Packet(req, MemCmd::WriteReq);
724        pkt->refineCommand();
725        return pkt;
726    }
727
728    /**
729     * clean up packet variables
730     */
731    ~Packet()
732    {
733        // If this is a request packet for which there's no response,
734        // delete the request object here, since the requester will
735        // never get the chance.
736        if (req && isRequest() && !needsResponse())
737            delete req;
738        deleteData();
739    }
740
741    /**
742     * Take a request packet and modify it in place to be suitable for
743     * returning as a response to that request. The source field is
744     * turned into the destination, and subsequently cleared. Note
745     * that the latter is not necessary for atomic requests, but
746     * causes no harm as neither field is valid.
747     */
748    void
749    makeResponse()
750    {
751        assert(needsResponse());
752        assert(isRequest());
753        origCmd = cmd;
754        cmd = cmd.responseCommand();
755
756        // responses are never express, even if the snoop that
757        // triggered them was
758        flags.clear(EXPRESS_SNOOP);
759
760        dest = src;
761        src = InvalidPortID;
762    }
763
764    void
765    makeAtomicResponse()
766    {
767        makeResponse();
768    }
769
770    void
771    makeTimingResponse()
772    {
773        makeResponse();
774    }
775
776    void
777    setFunctionalResponseStatus(bool success)
778    {
779        if (!success) {
780            if (isWrite()) {
781                cmd = MemCmd::FunctionalWriteError;
782            } else {
783                cmd = MemCmd::FunctionalReadError;
784            }
785        }
786    }
787
788    void
789    setSize(unsigned size)
790    {
791        assert(!flags.isSet(VALID_SIZE));
792
793        this->size = size;
794        flags.set(VALID_SIZE);
795    }
796
797
798    /**
799     * Set the data pointer to the following value that should not be
800     * freed. Static data allows us to do a single memcpy even if
801     * multiple packets are required to get from source to destination
802     * and back. In essence the pointer is set calling dataStatic on
803     * the original packet, and whenever this packet is copied and
804     * forwarded the same pointer is passed on. When a packet
805     * eventually reaches the destination holding the data, it is
806     * copied once into the location originally set. On the way back
807     * to the source, no copies are necessary.
808     */
809    template <typename T>
810    void
811    dataStatic(T *p)
812    {
813        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
814        data = (PacketDataPtr)p;
815        flags.set(STATIC_DATA);
816    }
817
818    /**
819     * Set the data pointer to the following value that should not be
820     * freed. This version of the function allows the pointer passed
821     * to us to be const. To avoid issues down the line we cast the
822     * constness away, the alternative would be to keep both a const
823     * and non-const data pointer and cleverly choose between
824     * them. Note that this is only allowed for static data.
825     */
826    template <typename T>
827    void
828    dataStaticConst(const T *p)
829    {
830        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
831        data = const_cast<PacketDataPtr>(p);
832        flags.set(STATIC_DATA);
833    }
834
835    /**
836     * Set the data pointer to a value that should have delete []
837     * called on it. Dynamic data is local to this packet, and as the
838     * packet travels from source to destination, forwarded packets
839     * will allocate their own data. When a packet reaches the final
840     * destination it will populate the dynamic data of that specific
841     * packet, and on the way back towards the source, memcpy will be
842     * invoked in every step where a new packet was created e.g. in
843     * the caches. Ultimately when the response reaches the source a
844     * final memcpy is needed to extract the data from the packet
845     * before it is deallocated.
846     */
847    template <typename T>
848    void
849    dataDynamic(T *p)
850    {
851        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
852        data = (PacketDataPtr)p;
853        flags.set(DYNAMIC_DATA);
854    }
855
856    /**
857     * get a pointer to the data ptr.
858     */
859    template <typename T>
860    T*
861    getPtr()
862    {
863        assert(flags.isSet(STATIC_DATA|DYNAMIC_DATA));
864        return (T*)data;
865    }
866
867    template <typename T>
868    const T*
869    getConstPtr() const
870    {
871        assert(flags.isSet(STATIC_DATA|DYNAMIC_DATA));
872        return (const T*)data;
873    }
874
875    /**
876     * return the value of what is pointed to in the packet.
877     */
878    template <typename T>
879    T get() const;
880
881    /**
882     * set the value in the data pointer to v.
883     */
884    template <typename T>
885    void set(T v);
886
887    /**
888     * Copy data into the packet from the provided pointer.
889     */
890    void
891    setData(const uint8_t *p)
892    {
893        // we should never be copying data onto itself, which means we
894        // must idenfity packets with static data, as they carry the
895        // same pointer from source to destination and back
896        assert(p != getPtr<uint8_t>() || flags.isSet(STATIC_DATA));
897
898        if (p != getPtr<uint8_t>())
899            // for packet with allocated dynamic data, we copy data from
900            // one to the other, e.g. a forwarded response to a response
901            std::memcpy(getPtr<uint8_t>(), p, getSize());
902    }
903
904    /**
905     * Copy data into the packet from the provided block pointer,
906     * which is aligned to the given block size.
907     */
908    void
909    setDataFromBlock(const uint8_t *blk_data, int blkSize)
910    {
911        setData(blk_data + getOffset(blkSize));
912    }
913
914    /**
915     * Copy data from the packet to the provided block pointer, which
916     * is aligned to the given block size.
917     */
918    void
919    writeData(uint8_t *p) const
920    {
921        std::memcpy(p, getConstPtr<uint8_t>(), getSize());
922    }
923
924    /**
925     * Copy data from the packet to the memory at the provided pointer.
926     */
927    void
928    writeDataToBlock(uint8_t *blk_data, int blkSize) const
929    {
930        writeData(blk_data + getOffset(blkSize));
931    }
932
933    /**
934     * delete the data pointed to in the data pointer. Ok to call to
935     * matter how data was allocted.
936     */
937    void
938    deleteData()
939    {
940        if (flags.isSet(DYNAMIC_DATA))
941            delete [] data;
942
943        flags.clear(STATIC_DATA|DYNAMIC_DATA);
944        data = NULL;
945    }
946
947    /** Allocate memory for the packet. */
948    void
949    allocate()
950    {
951        assert(flags.noneSet(STATIC_DATA|DYNAMIC_DATA));
952        flags.set(DYNAMIC_DATA);
953        data = new uint8_t[getSize()];
954    }
955
956    /**
957     * Check a functional request against a memory value stored in
958     * another packet (i.e. an in-transit request or
959     * response). Returns true if the current packet is a read, and
960     * the other packet provides the data, which is then copied to the
961     * current packet. If the current packet is a write, and the other
962     * packet intersects this one, then we update the data
963     * accordingly.
964     */
965    bool
966    checkFunctional(PacketPtr other)
967    {
968        // all packets that are carrying a payload should have a valid
969        // data pointer
970        return checkFunctional(other, other->getAddr(), other->isSecure(),
971                               other->getSize(),
972                               other->hasData() ?
973                               other->getPtr<uint8_t>() : NULL);
974    }
975
976    /**
977     * Check a functional request against a memory value represented
978     * by a base/size pair and an associated data array. If the
979     * current packet is a read, it may be satisfied by the memory
980     * value. If the current packet is a write, it may update the
981     * memory value.
982     */
983    bool
984    checkFunctional(Printable *obj, Addr base, bool is_secure, int size,
985                    uint8_t *_data);
986
987    /**
988     * Push label for PrintReq (safe to call unconditionally).
989     */
990    void
991    pushLabel(const std::string &lbl)
992    {
993        if (isPrint())
994            safe_cast<PrintReqState*>(senderState)->pushLabel(lbl);
995    }
996
997    /**
998     * Pop label for PrintReq (safe to call unconditionally).
999     */
1000    void
1001    popLabel()
1002    {
1003        if (isPrint())
1004            safe_cast<PrintReqState*>(senderState)->popLabel();
1005    }
1006
1007    void print(std::ostream &o, int verbosity = 0,
1008               const std::string &prefix = "") const;
1009
1010    /**
1011     * A no-args wrapper of print(std::ostream...)
1012     * meant to be invoked from DPRINTFs
1013     * avoiding string overheads in fast mode
1014     * @return string with the request's type and start<->end addresses
1015     */
1016    std::string print() const;
1017};
1018
1019#endif //__MEM_PACKET_HH
1020