sid/include/sidcomp.h

   1 // sidcomp.h - Define the external interface of a SID component, that
   2 // is, the SID component API expressed in -*- C++ -*-.
   3
   4 // Copyright (C) 1999, 2000 Red Hat.
   5 // This file is part of SID and is licensed under the GPL.
   6 // See the file COPYING.SID for conditions for redistribution.
   7
   8 #ifndef SIDCOMP_H
   9 #define SIDCOMP_H
  10
  11 #include <sidtypes.h>
  12
  13 #include <string>
  14 #include <vector>
  15
  16 namespace sid
  17 {
  18   // PART 0: Basic declarations
  19   // Together, these numbers describe the API as defined in the
  20   // abstract sid:: classes.  Every time the API changes, a new number
  21   // pair needs to be assigned.  These numbers figure in the
  22   // COMPONENT_LIBRARY_MAGIC mechanism in sidso.h, and prevents
  23   // interopration attempts with obsolete component objects.
  24
  25   const unsigned API_MAJOR_VERSION = 2;
  26   const unsigned API_MINOR_VERSION = 2;
  27
  28   // PART 1: Buses
  29   //
  30   // The abstract class sid::bus defines a function-call oriented
  31   // model of a hardware data/address/control bus.  It supports a
  32   // 32-bit address space, and allows reads and writes with data of
  33   // varying lengths.  The sid::bus class is the slave that provides
  34   // the data.  A bus accessor is the bus master which requests the
  35   // data.  One component's bus accessor is connected to another's bus
  36   // with the connect_accessor() method.
  37
  38   class bus
  39   {
  40   public:
  41     // status values from read/write calls.
  42     enum status
  43     {
  44       ok           = 0x00, // done, no problems
  45       misaligned   = 0x01, // address misaligned
  46       unmapped     = 0x02, // address not in mapped range
  47       unpermitted  = 0x04, // may not read or may not write at address
  48       delayed      = 0x10, // data not yet available - try again after yielding
  49     };
  50
  51
  52     // These member functions enumerate the Cartesian product of all
  53     // possible access requests to a bus:
  54     // {data-endianness} X {addr-width} X {data-width}
  55     //  little,big         4               1,2,4,8
  56
  57     // Write data at given address.
  58
  59     virtual status write(host_int_4 addr, big_int_1 data)
  60       throw () = 0;
  61
  62     virtual status write(host_int_4 addr, little_int_1 data)
  63       throw () = 0;
  64
  65     virtual status write(host_int_4 addr, big_int_2 data)
  66       throw () = 0;
  67
  68     virtual status write(host_int_4 addr, little_int_2 data)
  69       throw () = 0;
  70
  71     virtual status write(host_int_4 addr, big_int_4 data)
  72       throw () = 0;
  73
  74     virtual status write(host_int_4 addr, little_int_4 data)
  75       throw () = 0;
  76
  77     virtual status write(host_int_4 addr, big_int_8 data)
  78       throw () = 0;
  79
  80     virtual status write(host_int_4 addr, little_int_8 data)
  81       throw () = 0;
  82
  83     // Write data from given address.
  84     virtual status
  85     read(host_int_4 addr, big_int_1& data)
  86       throw () = 0;
  87
  88     virtual status
  89     read(host_int_4 addr, little_int_1& data)
  90       throw()= 0;
  91
  92     virtual status
  93     read(host_int_4 addr, big_int_2& data)
  94       throw () = 0;
  95
  96     virtual status
  97     read(host_int_4 addr, little_int_2& data)
  98       throw()= 0;
  99
 100     virtual status
 101     read(host_int_4 addr, big_int_4& data)
 102       throw () = 0;
 103
 104     virtual status
 105     read(host_int_4 addr, little_int_4& data)
 106       throw()= 0;
 107
 108     virtual status
 109     read(host_int_4 addr, big_int_8& data)
 110       throw () = 0;
 111
 112     virtual status
 113     read(host_int_4 addr, little_int_8& data)
 114       throw()= 0;
 115
 116   protected:
 117     bus() {}
 118     virtual ~bus() throw() {}
 119   };
 120
 121
 122   // PART 2: Pins
 123   //
 124   // The abstract pin class is one of the methods by which components
 125   // communicate.  The sid::pin class represents the input side of a
 126   // pin->pin connection.  Incoming signals are represented by calls
 127   // on the driven() method.  Outgoing signals may be sent to other
 128   // components' pins after they are given to a component using the
 129   // connect_pin() method.
 130
 131   class pin
 132   {
 133   public:
 134     // A notification that the pin has been driven with some value.
 135     virtual void driven(host_int_4 value) throw () = 0;
 136
 137   protected:
 138     pin() {}
 139     virtual ~pin() throw() {}
 140   };
 141
 142
 143   // PART 3: Components
 144   //
 145   // The abstract component class is the basic building block of a
 146   // simulator.  Components are connected together to create complete
 147   // simulations.  There are several types of connections: pins, buses
 148   // and relations.
 149
 150   class component
 151   {
 152   public:
 153     // Status indications for various calls.
 154     enum status
 155     {
 156       ok        = 0,    // successful
 157       not_found = -1,   // lookup key invalid
 158       bad_value = -2    // illegal parameter
 159     };
 160
 161     // PART 3.1: instantiation
 162   protected:
 163     component() {}
 164     virtual ~component() throw() {}
 165
 166   public:
 167     // PART 3.2: attributes (SUPERVISORY)
 168
 169     // List the names of all your attributes.
 170     virtual std::vector<std::string>
 171     attribute_names()
 172       throw() = 0;
 173
 174     // List the names of your attributes in a given category.
 175     virtual std::vector<std::string>
 176     attribute_names(const std::string& category)
 177       throw() = 0;
 178
 179     // Get the value of your named attribute.
 180     // Return an empty string on failure.
 181     virtual std::string
 182     attribute_value(const std::string& name)
 183       throw() = 0;
 184
 185     // Set your named attribute to a given value.
 186     // Returns component::ok only if sucessful.
 187     virtual status
 188     set_attribute_value(const std::string& name, const std::string& value)
 189       throw() = 0;
 190
 191
 192     // PART 3.3: pins (SUPERVISORY)
 193   public:
 194     // List all your pin names.  Include all input pins (for use with
 195     // find_pin) and output pins (for use with connect_pin etc.).
 196     virtual std::vector<std::string>
 197     pin_names()
 198       throw() = 0;
 199
 200     // Find input pin with given name.
 201     // Return a pointer to your pin or 0 if the pin is not found.
 202     virtual pin*
 203     find_pin(const std::string& name)
 204       throw() = 0;
 205
 206     // Add new connection between your named output pin to given input pin.
 207     virtual status
 208     connect_pin(const std::string& name, pin* pin)
 209       throw() = 0;
 210
 211     // Remove connection between your named output pin from given input pin.
 212     virtual status
 213     disconnect_pin(const std::string& name, pin* pin)
 214       throw()= 0;
 215
 216     // List all pins connected to your named output pin.
 217     virtual std::vector<pin*>
 218     connected_pins(const std::string& name)
 219       throw() = 0;
 220
 221
 222     // PART 3.4: buses & accessors (SUPERVISORY)
 223   public:
 224     // List the names of your buses.
 225     virtual std::vector<std::string>
 226     bus_names()
 227       throw() = 0;
 228
 229     // Find a bus of the given name.
 230     // Return a pointer to your bus, or 0 if the bus is not found.
 231     virtual bus*
 232     find_bus(const std::string& name)
 233       throw() = 0;
 234
 235     // List the names of your bus accessors.
 236     virtual std::vector<std::string>
 237     accessor_names()
 238       throw() = 0;
 239
 240     // Connect your named accessor to a given bus.
 241     virtual status
 242     connect_accessor(const std::string& name, bus* bus)
 243       throw() = 0;
 244
 245     // Disconnect your named accessor from a given bus.
 246     virtual status
 247     disconnect_accessor(const std::string& name, bus* bus)
 248       throw() = 0;
 249
 250     // Return the bus connected to your named accessor.
 251     virtual bus*
 252     connected_bus(const std::string& name)
 253       throw() = 0;
 254
 255
 256     // PART 3.5: component enumeration (SUPERVISORY)
 257   public:
 258     // List the names of your component relationship lists.
 259     virtual std::vector<std::string>
 260     relationship_names()
 261       throw() = 0;
 262
 263     // Add given component to your named relationship list.
 264     virtual status
 265     relate (const std::string& name, component* comp)
 266       throw () = 0;
 267
 268     // Remove given component from your named relationship list.
 269     virtual status
 270     unrelate (const std::string& name, component* comp)
 271       throw () = 0;
 272
 273     // List components in your named relationship list.  Return
 274     // empty list if relationship is not found.
 275     virtual std::vector<component*>
 276     related_components (const std::string& name)
 277       throw () = 0;
 278   };
 279 }
 280
 281 #endif // SIDCOMP_H