src/mem/ruby/libruby.hh

   1 /*
   2  * Copyright (c) 2009 Mark D. Hill and David A. Wood
   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 #ifndef LIBRUBY_H
  30 #define LIBRUBY_H
  31
  32 #include <stdint.h>
  33 #include <ostream>
  34 #include "mem/packet.hh"
  35
  36 typedef void* RubyPortHandle;
  37 enum RubyRequestType {
  38   RubyRequestType_NULL,
  39   RubyRequestType_IFETCH,
  40   RubyRequestType_LD,
  41   RubyRequestType_ST,
  42   RubyRequestType_Locked_Read,
  43   RubyRequestType_Locked_Write,
  44   RubyRequestType_RMW_Read,
  45   RubyRequestType_RMW_Write,
  46   RubyRequestType_NUM
  47 };
  48
  49 enum RubyAccessMode {
  50   RubyAccessMode_User,
  51   RubyAccessMode_Supervisor,
  52   RubyAccessMode_Device
  53 };
  54
  55 struct RubyRequest {
  56   uint64_t paddr;
  57   uint8_t* data;
  58   int len;
  59   uint64_t pc;
  60   RubyRequestType type;
  61   RubyAccessMode access_mode;
  62   PacketPtr pkt;
  63   unsigned proc_id;
  64
  65   RubyRequest() {}
  66   RubyRequest(uint64_t _paddr,
  67               uint8_t* _data,
  68               int _len,
  69               uint64_t _pc,
  70               RubyRequestType _type,
  71               RubyAccessMode _access_mode,
  72               PacketPtr _pkt,
  73               unsigned _proc_id = 100)
  74     : paddr(_paddr),
  75       data(_data),
  76       len(_len),
  77       pc(_pc),
  78       type(_type),
  79       access_mode(_access_mode),
  80       pkt(_pkt),
  81       proc_id(_proc_id)
  82   {}
  83 };
  84
  85 std::ostream& operator<<(std::ostream& out, const RubyRequest& obj);
  86
  87 /**
  88  * Initialize the system.  cfg_file is a Ruby-lang configuration script
  89  */
  90 void libruby_init(const char* cfg_file);
  91
  92 /**
  93  * Tear down a configured system.  Must be invoked after a call to libruby_init.
  94  */
  95 void libruby_destroy();
  96
  97 /**
  98  * Print the last error encountered by ruby.  Currently unimplemented.
  99  */
 100 const char* libruby_last_error();
 101
 102 /**
 103  *  Retrieve a handle to a RubyPort object, identified by name in the
 104  *  configuration.  You also pass in the callback function you want
 105  *  this port to use when a request completes.  Only one handle to a
 106  *  port is allowed at a time.
 107  */
 108 RubyPortHandle libruby_get_port(const char* name, void (*hit_callback)(int64_t access_id));
 109
 110 /**
 111  *  Retrieve a handle to a RubyPort object, identified by name in the
 112  *  configuration.
 113  */
 114 RubyPortHandle libruby_get_port_by_name(const char* name);
 115
 116
 117 /**
 118  * issue_request returns a unique access_id to identify the ruby
 119  * transaction. This access_id is later returned to the caller via
 120  * hit_callback (passed to libruby_get_port)
 121  */
 122 int64_t libruby_issue_request(RubyPortHandle p, struct RubyRequest request);
 123
 124 /**
 125  * writes data directly into Ruby's data array.  Note that this
 126  * ignores caches, and should be considered incoherent after
 127  * simulation starts.
 128  */
 129 void libruby_write_ram(uint64_t paddr, uint8_t * data, int len);
 130
 131 /**
 132  * reads data directory from Ruby's data array.  Note that this
 133  * ignores caches, and should be considered incoherent after
 134  * simulation starts
 135  */
 136 void libruby_read_ram(uint64_t paddr, uint8_t * data, int len);
 137
 138 /**
 139  * tick the system n cycles.  Eventually, will return the number of
 140  * cycles until the next event, but for now it always returns 0
 141  */
 142 int libruby_tick(int n);
 143
 144 /**
 145  *  self explainitory
 146  */
 147 void libruby_print_config(std::ostream & out);
 148
 149 /**
 150  * self explainitory
 151  */
 152 void libruby_print_stats(std::ostream & out);
 153
 154 /**
 155  * does not return until done
 156  */
 157 void libruby_playback_trace(char * trace_filename);
 158
 159 /*
 160  * enables the tracer and opens the trace file
 161  */
 162 void libruby_start_tracing(char * record_filename);
 163
 164 /*
 165  * closes the trace file
 166  */
 167 void libruby_stop_tracing();
 168
 169 /**
 170  * get time
 171  */
 172 uint64_t libruby_get_time();
 173 #endif