port.hh revision 2405
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 bool recvTiming(Packet &pkt) = 0; 91 92 /** Called to recive a atomic call from the peer port. */ 93 virtual Tick recvAtomic(Packet &pkt) = 0; 94 95 /** Called to recive a functional call from the peer port. */ 96 virtual void recvFunctional(Packet &pkt) = 0; 97 98 /** Called to recieve a status change from the peer port. */ 99 virtual void recvStatusChange(Status status) = 0; 100 101 /** Called by a peer port if the send was unsuccesful, and had to 102 wait. This shouldn't be valid for response paths (IO Devices). 103 so it is set to panic if it isn't already defined. 104 */ 105 virtual Packet *recvRetry() { panic("??"); } 106 107 /** Called by a peer port in order to determine the block size of the 108 device connected to this port. It sometimes doesn't make sense for 109 this function to be called, a DMA interface doesn't really have a 110 block size, so it is defaulted to a panic. 111 */ 112 virtual int recvBlockSizeQuery() { panic("??"); } 113 114 /** The peer port is requesting us to reply with a list of the ranges we 115 are responsible for. 116 @param owner is an output param that, if set, indicates that the 117 port is the owner of the specified ranges (i.e., slave, default 118 responder, etc.). If 'owner' is false, the interface is 119 interested in the specified ranges for snooping purposes. If 120 an object wants to own some ranges and snoop on others, it will 121 need to use two different ports. 122 */ 123 virtual void recvAddressRangesQuery(std::list<Range<Addr> > &range_list, 124 bool &owner) { panic("??"); } 125 126 public: 127 128 /** Function called by associated memory device (cache, memory, iodevice) 129 in order to send a timing request to the port. Simply calls the peer 130 port receive function. 131 @return This function returns if the send was succesful in it's 132 recieve. If it was a failure, then the port will wait for a recvRetry 133 at which point it can issue a successful sendTiming. This is used in 134 case a cache has a higher priority request come in while waiting for 135 the bus to arbitrate. 136 */ 137 bool sendTiming(Packet &pkt) { return peer->recvTiming(pkt); } 138 139 /** Function called by the associated device to send an atomic access, 140 an access in which the data is moved and the state is updated in one 141 cycle, without interleaving with other memory accesses. 142 */ 143 Tick sendAtomic(Packet &pkt) 144 { return peer->recvAtomic(pkt); } 145 146 /** Function called by the associated device to send a functional access, 147 an access in which the data is instantly updated everywhere in the 148 memory system, without affecting the current state of any block 149 or moving the block. 150 */ 151 void sendFunctional(Packet &pkt) 152 { return peer->recvFunctional(pkt); } 153 154 /** Called by the associated device to send a status change to the device 155 connected to the peer interface. 156 */ 157 void sendStatusChange(Status status) {peer->recvStatusChange(status); } 158 159 /** When a timing access doesn't return a success, some time later the 160 Retry will be sent. 161 */ 162 Packet *sendRetry() { return peer->recvRetry(); } 163 164 /** Called by the associated device if it wishes to find out the blocksize 165 of the device on attached to the peer port. 166 */ 167 int sendBlockSizeQuery() { return peer->recvBlockSizeQuery(); } 168 169 /** Called by the associated device if it wishes to find out the address 170 ranges connected to the peer ports devices. 171 */ 172 void sendAddressRangesQuery(std::list<Range<Addr> > &range_list, 173 bool &owner) 174 { peer->recvAddressRangesQuery(range_list, owner); } 175 176 // Do we need similar wrappers for sendAtomic()? If not, should 177 // we drop the "Functional" from the names? 178 179 /** This function is a wrapper around sendFunctional() 180 that breaks a larger, arbitrarily aligned access into 181 appropriate chunks. The default implementation can use 182 getBlockSize() to determine the block size and go from there. 183 */ 184 void readBlobFunctional(Addr addr, uint8_t *p, int size); 185 186 /** This function is a wrapper around sendFunctional() 187 that breaks a larger, arbitrarily aligned access into 188 appropriate chunks. The default implementation can use 189 getBlockSize() to determine the block size and go from there. 190 */ 191 void writeBlobFunctional(Addr addr, uint8_t *p, int size); 192 193 /** Fill size bytes starting at addr with byte value val. This 194 should not need to be virtual, since it can be implemented in 195 terms of writeBlobFunctional(). However, it shouldn't be 196 performance-critical either, so it could be if we wanted to. 197 Not even sure if this is actually needed anywhere (there's a 198 prot_memset on the old functional memory that's never used), 199 but Nate claims it is. 200 */ 201 void memsetBlobFunctional(Addr addr, uint8_t val, int size); 202 203 private: 204 205 /** Internal helper function for read/writeBlob(). 206 */ 207 void blobHelper(Addr addr, uint8_t *p, int size, Command cmd); 208}; 209 210#endif //__MEM_PORT_HH__ 211