port.hh revision 2381
1/* 2 * Copyright (c) 2002-2005 The Regents of The University of Michigan 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are 7 * met: redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer; 9 * redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution; 12 * neither the name of the copyright holders nor the names of its 13 * contributors may be used to endorse or promote products derived from 14 * this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 18 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 19 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 20 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 21 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 22 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 26 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29/** 30 * @file 31 * Port Object Decleration. Ports are used to interface memory objects to 32 * each other. They will always come in pairs, and we refer to the other 33 * port object as the peer. These are used to make the design more 34 * modular so that a specific interface between every type of objcet doesn't 35 * have to be created. 36 */ 37 38#ifndef __MEM_PORT_HH__ 39#define __MEM_PORT_HH__ 40 41#include <string> 42#include <list> 43#include <inttypes.h> 44 45#include "base/range.hh" 46#include "mem/packet.hh" 47#include "mem/request.hh" 48 49/** 50 * Ports are used to interface memory objects to 51 * each other. They will always come in pairs, and we refer to the other 52 * port object as the peer. These are used to make the design more 53 * modular so that a specific interface between every type of objcet doesn't 54 * have to be created. 55 * 56 * Recv accesor functions are being called from the peer interface. 57 * Send accessor functions are being called from the device the port is 58 * associated with, and it will call the peer recv. accessor function. 59 */ 60class Port 61{ 62 public: 63 64 // mey be better to use subclasses & RTTI? 65 /** Holds the ports status. Keeps track if it is blocked, or has 66 calculated a range change. */ 67 enum Status { 68 Blocked, 69 Unblocked, 70 RangeChange 71 }; 72 73 private: 74 75 /** A pointer to the peer port. Ports always come in pairs, that way they 76 can use a standardized interface to communicate between different 77 memory objects. */ 78 Port *peer; 79 80 public: 81 82 /** Function to set the pointer for the peer port. 83 @todo should be called by the configuration stuff (python). 84 */ 85 void setPeer(Port *port) { peer = port; } 86 87 protected: 88 89 /** Called to recive a timing call from the peer port. */ 90 virtual SendResult recvTiming(Packet &pkt) = 0; 91 92 /** Virtual function that can be used to handle scheduling an event 93 to send the recvTiming at a given time. This is for direct 94 connection without a interconnect. The bus will override 95 this in it's port class because the bus does the timing. 96 This is used to insert timing when an interconnect doesn't 97 have it's own event queue. 98 */ 99 virtual SendResult recvTiming(Packet &pkt, Tick t) 100 { 101 // schedule event to call recvTiming(pkt) @ tick t 102 } 103 104 /** Called to recive a atomic call from the peer port. */ 105 virtual SendResult recvAtomic(Packet &pkt) = 0; 106 107 /** Called to recive a functional call from the peer port. */ 108 virtual SendResult recvFunctional(Packet &pkt) = 0; 109 110 /** Called to recieve a status change from the peer port. */ 111 virtual void recvStatusChange(Status status) = 0; 112 113 /** Called by a peer port if the send was unsuccesful, and had to 114 wait. This shouldn't be valid for response paths (IO Devices). 115 so it is set to panic if it isn't already defined. 116 */ 117 virtual Packet *recvRetry() { panic("??"); } 118 119 /** Called by a peer port in order to determine the block size of the 120 device connected to this port. It sometimes doesn't make sense for 121 this function to be called, a DMA interface doesn't really have a 122 block size, so it is defaulted to a panic. 123 */ 124 virtual int recvBlockSizeQuery() { panic("??"); } 125 126 /** The peer port is requesting us to reply with a list of the ranges we 127 are responsible for. 128 @param owner is an output param that, if set, indicates that the 129 port is the owner of the specified ranges (i.e., slave, default 130 responder, etc.). If 'owner' is false, the interface is 131 interested in the specified ranges for snooping purposes. If 132 an object wants to own some ranges and snoop on others, it will 133 need to use two different ports. 134 */ 135 virtual void recvAddressRangeQuery(std::list<Range<Addr> > &range_list, 136 bool &owner) = 0; 137 138 public: 139 140 /** Function called by associated memory device (cache, memory, iodevice) 141 in order to send a timing request to the port. Simply calls the peer 142 port receive function. 143 @return This function returns if the send was succesful in it's 144 recieve. If it was a failure, then the port will wait for a recvRetry 145 at which point it can issue a successful sendTiming. This is used in 146 case a cache has a higher priority request come in while waiting for 147 the bus to arbitrate. 148 */ 149 SendResult sendTiming(Packet &pkt) { return peer->recvTiming(pkt); } 150 151 /** This function is identical to the sendTiming function, accept it 152 provides a time when the recvTiming should be called. The 153 peer->recvTimimng will schedule the event, if it's device handles the 154 timing (bus) it will be overloaded by the bus type port to handle it 155 properly. 156 */ 157 SendResult sendTiming(Packet &pkt, Tick t) { return peer->recvTiming(pkt, t); } 158 159 /** Function called by the associated device to send an atomic access, 160 an access in which the data is moved and the state is updated in one 161 cycle, without interleaving with other memory accesses. 162 */ 163 SendResult sendAtomic(Packet &pkt) 164 { return peer->recvAtomic(pkt); } 165 166 /** Function called by the associated device to send a functional access, 167 an access in which the data is instantly updated everywhere in the 168 memory system, without affecting the current state of any block 169 or moving the block. 170 */ 171 SendResult sendFunctional(Packet &pkt) 172 { return peer->recvFunctional(pkt); } 173 174 /** Called by the associated device to send a status change to the device 175 connected to the peer interface. 176 */ 177 void sendStatusChange(Status status) {peer->recvStatusChange(status); } 178 179 /** When a timing access doesn't return a success, some time later the 180 Retry will be sent. 181 */ 182 Packet *sendRetry() { return peer->recvRetry(); } 183 184 /** Called by the associated device if it wishes to find out the blocksize 185 of the device on attached to the peer port. 186 */ 187 int sendBlockSizeQuery() { return peer->recvBlockSizeQuery(); } 188 189 /** Called by the associated device if it wishes to find out the address 190 ranges connected to the peer ports devices. 191 */ 192 void sendAddressRangesQuery(std::list<Range<Addr> > &range_list, 193 bool &owner) 194 { peer->recvAddressRangesQuery(range_list, owner); } 195 196 // For the read/write blob functional 197 // This should be sufficient for everything except ProxyMemory 198 // which needs to slip a translation step in as well. (Unless it 199 // does the translation underneath sendFunctional(), in which case 200 // maybe this doesn't need to be virtual at all.) Do we need 201 // similar wrappers for sendAtomic()? If not, should we drop the 202 // "Functional" from the names? 203 204 /** This function is a wrapper around sendFunctional() 205 that breaks a larger, arbitrarily aligned access into 206 appropriate chunks. The default implementation can use 207 getBlockSize() to determine the block size and go from there. 208 */ 209 virtual void readBlobFunctional(Addr addr, uint8_t *p, int size); 210 211 /** This function is a wrapper around sendFunctional() 212 that breaks a larger, arbitrarily aligned access into 213 appropriate chunks. The default implementation can use 214 getBlockSize() to determine the block size and go from there. 215 */ 216 virtual void writeBlobFunctional(Addr addr, const uint8_t *p, int size); 217 218 /** Fill size bytes starting at addr with byte value val. This 219 should not need to be virtual, since it can be implemented in 220 terms of writeBlobFunctional(). However, it shouldn't be 221 performance-critical either, so it could be if we wanted to. 222 Not even sure if this is actually needed anywhere (there's a 223 prot_memset on the old functional memory that's never used), 224 but Nate claims it is. 225 */ 226 void memsetBlobFunctional(Addr addr, uint8_t val, int size); 227 228 // I believe these two string functions can be defined once and 229 // for all at the top level by implementing them in terms of 230 // readBlob and writeBlob. 231 232 /** Write null-terminated string 'str' into memory at 'addr'. */ 233 void writeStringFunctional(Addr addr, const char *str); 234 235 /** Read null-terminated string from 'addr' into 'str'. */ 236 void readStringFunctional(std::string &str, Addr addr); 237}; 238 239#endif //__MEM_PORT_HH__ 240