era.mi/src/era/mi/logic/wires/Wire.java

   1 package era.mi.logic.wires;\r
   2 \r
   3 import static era.mi.logic.types.Bit.U;\r
   4 import static era.mi.logic.types.Bit.Z;\r
   5 \r
   6 import java.util.ArrayList;\r
   7 import java.util.List;\r
   8 \r
   9 import era.mi.logic.Simulation;\r
  10 import era.mi.logic.types.Bit;\r
  11 import era.mi.logic.types.BitVector;\r
  12 import era.mi.logic.types.BitVector.BitVectorMutator;\r
  13 \r
  14 /**\r
  15  * Represents an array of wires that can store n bits of information.\r
  16  * \r
  17  * @author Fabian Stemmler\r
  18  *\r
  19  */\r
  20 public class Wire\r
  21 {\r
  22         private BitVector values;\r
  23         public final int travelTime;\r
  24         private List<ReadEnd> attached = new ArrayList<ReadEnd>();\r
  25         public final int length;\r
  26         private List<ReadWriteEnd> inputs = new ArrayList<ReadWriteEnd>();\r
  27 \r
  28         public Wire(int length, int travelTime)\r
  29         {\r
  30                 if (length < 1)\r
  31                         throw new IllegalArgumentException(\r
  32                                         String.format("Tried to create an array of wires with length %d, but a length of less than 1 makes no sense.", length));\r
  33                 this.length = length;\r
  34                 this.travelTime = travelTime;\r
  35                 initValues();\r
  36         }\r
  37 \r
  38         private void initValues()\r
  39         {\r
  40                 values = U.toVector(length);\r
  41         }\r
  42 \r
  43         private void recalculateSingleInput()\r
  44         {\r
  45                 setNewValues(inputs.get(0).getInputValues());\r
  46         }\r
  47 \r
  48         private void recalculateMultipleInputs()\r
  49         {\r
  50                 BitVectorMutator mutator = BitVectorMutator.empty();\r
  51                 for (ReadWriteEnd wireArrayEnd : inputs)\r
  52                         mutator.join(wireArrayEnd.getInputValues());\r
  53                 setNewValues(mutator.get());\r
  54         }\r
  55 \r
  56         private void setNewValues(BitVector newValues)\r
  57         {\r
  58                 if (values.equals(newValues))\r
  59                         return;\r
  60                 BitVector oldValues = values;\r
  61                 values = newValues;\r
  62                 notifyObservers(oldValues);\r
  63         }\r
  64 \r
  65         private void recalculate()\r
  66         {\r
  67                 switch (inputs.size())\r
  68                 {\r
  69                 case 0:\r
  70                         return;\r
  71                 case 1:\r
  72                         recalculateSingleInput();\r
  73                         break;\r
  74                 default:\r
  75                         recalculateMultipleInputs();\r
  76                 }\r
  77         }\r
  78 \r
  79         /**\r
  80          * The {@link Wire} is interpreted as an unsigned integer with n bits.\r
  81          * \r
  82          * @return <code>true</code> if all bits are either <code>Bit.ONE</code> or <code>Bit.ZERO</code> (they do not all have to have the same\r
  83          *         value), not <code>Bit.X</code> or <code>Bit.Z</code>. <code>false</code> is returned otherwise.\r
  84          * \r
  85          * @author Fabian Stemmler\r
  86          */\r
  87         public boolean hasNumericValue()\r
  88         {\r
  89                 for (Bit b : values)\r
  90                 {\r
  91                         if (b != Bit.ZERO && b != Bit.ONE)\r
  92                                 return false;\r
  93                 }\r
  94                 return true;\r
  95         }\r
  96 \r
  97         /**\r
  98          * The {@link Wire} is interpreted as an unsigned integer with n bits.\r
  99          * \r
 100          * @return The unsigned value of the {@link Wire}'s bits, where value 0 corresponds with 2^0, value 1 is 2^1 and so on.\r
 101          * \r
 102          * @author Fabian Stemmler\r
 103          */\r
 104         public long getUnsignedValue()\r
 105         {\r
 106                 long val = 0;\r
 107                 long mask = 1;\r
 108                 for (Bit bit : values)\r
 109                 {\r
 110                         switch (bit)\r
 111                         {\r
 112                         default:\r
 113                         case Z:\r
 114                         case X:\r
 115                                 return 0; // TODO: Proper handling for getUnsignedValue(), if not all bits are 1 or 0;\r
 116                         case ONE:\r
 117                                 val |= mask;\r
 118                                 break;\r
 119                         case ZERO:\r
 120                         }\r
 121                         mask = mask << 1;\r
 122                 }\r
 123                 return val;\r
 124         }\r
 125 \r
 126         /**\r
 127          * The {@link Wire} is interpreted as a signed integer with n bits.\r
 128          * \r
 129          * @return The signed value of the {@link Wire}'s bits, where value 0 corresponds with 2^0, value 1 is 2^1 and so on.\r
 130          * \r
 131          * @author Fabian Stemmler\r
 132          */\r
 133         public long getSignedValue()\r
 134         {\r
 135                 long val = getUnsignedValue();\r
 136                 long mask = 1 << (length - 1);\r
 137                 if ((mask & val) != 0)\r
 138                 {\r
 139                         int shifts = 64 - length;\r
 140                         return (val << shifts) >> shifts;\r
 141                 }\r
 142                 return val;\r
 143         }\r
 144 \r
 145         public Bit getValue()\r
 146         {\r
 147                 return getValue(0);\r
 148         }\r
 149 \r
 150         public Bit getValue(int index)\r
 151         {\r
 152                 return values.getBit(index);\r
 153         }\r
 154 \r
 155         public BitVector getValues(int start, int end)\r
 156         {\r
 157                 return values.subVector(start, end);\r
 158         }\r
 159 \r
 160         public BitVector getValues()\r
 161         {\r
 162                 return values;\r
 163         }\r
 164 \r
 165         /**\r
 166          * Adds an {@link WireObserver}, who will be notified when the value of the {@link Wire} is updated.\r
 167          * \r
 168          * @param ob The {@link WireObserver} to be notified of changes.\r
 169          * @return true if the given {@link WireObserver} was not already registered, false otherwise\r
 170          * \r
 171          * @author Fabian Stemmler\r
 172          */\r
 173         private void attachEnd(ReadEnd end)\r
 174         {\r
 175                 attached.add(end);\r
 176         }\r
 177 \r
 178         private void detachEnd(ReadEnd end)\r
 179         {\r
 180                 attached.remove(end);\r
 181         }\r
 182 \r
 183         private void notifyObservers(BitVector oldValues)\r
 184         {\r
 185                 for (ReadEnd o : attached)\r
 186                         o.update(oldValues);\r
 187         }\r
 188 \r
 189         /**\r
 190          * Create and register a {@link ReadWriteEnd} object, which is tied to this {@link Wire}. This {@link ReadWriteEnd} can be written to.\r
 191          */\r
 192         public ReadWriteEnd createEnd()\r
 193         {\r
 194                 return new ReadWriteEnd();\r
 195         }\r
 196 \r
 197         /**\r
 198          * Create a {@link ReadEnd} object, which is tied to this {@link Wire}. This {@link ReadEnd} cannot be written to.\r
 199          */\r
 200         public ReadEnd createReadOnlyEnd()\r
 201         {\r
 202                 return new ReadEnd();\r
 203         }\r
 204 \r
 205         private void registerInput(ReadWriteEnd toRegister)\r
 206         {\r
 207                 inputs.add(toRegister);\r
 208         }\r
 209 \r
 210         /**\r
 211          * A {@link ReadEnd} feeds a constant signal into the {@link Wire} it is tied to. The combination of all inputs determines the\r
 212          * {@link Wire}s final value. X dominates all other inputs Z does not affect the final value, unless there are no other inputs than Z 0\r
 213          * and 1 turn into X when they are mixed\r
 214          * \r
 215          * @author Fabian Stemmler\r
 216          */\r
 217         public class ReadEnd\r
 218         {\r
 219                 private List<WireObserver> observers = new ArrayList<WireObserver>();\r
 220 \r
 221                 private ReadEnd()\r
 222                 {\r
 223                         super();\r
 224                         Wire.this.attachEnd(this);\r
 225                 }\r
 226 \r
 227                 public void update(BitVector oldValues)\r
 228                 {\r
 229                         for (WireObserver ob : observers)\r
 230                                 ob.update(this, oldValues);\r
 231                 }\r
 232 \r
 233                 /**\r
 234                  * Included for convenient use on {@link Wire}s of length 1.\r
 235                  * \r
 236                  * @return The value of bit 0.\r
 237                  * \r
 238                  * @author Fabian Stemmler\r
 239                  */\r
 240                 public Bit getValue()\r
 241                 {\r
 242                         return Wire.this.getValue();\r
 243                 }\r
 244 \r
 245                 /**\r
 246                  * @param index Index of the requested bit.\r
 247                  * @return The value of the indexed bit.\r
 248                  * \r
 249                  * @author Fabian Stemmler\r
 250                  */\r
 251                 public Bit getValue(int index)\r
 252                 {\r
 253                         return Wire.this.getValue(index);\r
 254                 }\r
 255 \r
 256                 /**\r
 257                  * @param index Index of the requested bit.\r
 258                  * @return The value of the indexed bit.\r
 259                  * \r
 260                  * @author Fabian Stemmler\r
 261                  */\r
 262                 public BitVector getValues()\r
 263                 {\r
 264                         return Wire.this.getValues();\r
 265                 }\r
 266 \r
 267                 /**\r
 268                  * @param start Start of the wanted segment. (inclusive)\r
 269                  * @param end   End of the wanted segment. (exclusive)\r
 270                  * @return The values of the segment of {@link Bit}s indexed.\r
 271                  * \r
 272                  * @author Fabian Stemmler\r
 273                  */\r
 274                 public BitVector getValues(int start, int end)\r
 275                 {\r
 276                         return Wire.this.getValues(start, end);\r
 277                 }\r
 278 \r
 279                 /**\r
 280                  * The {@link Wire} is interpreted as an unsigned integer with n bits.\r
 281                  * \r
 282                  * @return <code>true</code> if all bits are either <code>Bit.ONE</code> or <code>Bit.ZERO</code> (they do not all have to have the\r
 283                  *         same value), not <code>Bit.X</code> or <code>Bit.Z</code>. <code>false</code> is returned otherwise.\r
 284                  * \r
 285                  * @author Fabian Stemmler\r
 286                  */\r
 287                 public boolean hasNumericValue()\r
 288                 {\r
 289                         return Wire.this.hasNumericValue();\r
 290                 }\r
 291 \r
 292                 /**\r
 293                  * The {@link Wire} is interpreted as an unsigned integer with n bits.\r
 294                  * \r
 295                  * @return The unsigned value of the {@link Wire}'s bits, where value 0 corresponds with 2^0, value 1 is 2^1 and so on.\r
 296                  * \r
 297                  * @author Fabian Stemmler\r
 298                  */\r
 299                 public long getUnsignedValue()\r
 300                 {\r
 301                         return Wire.this.getUnsignedValue();\r
 302                 }\r
 303 \r
 304                 /**\r
 305                  * The {@link Wire} is interpreted as a signed integer with n bits.\r
 306                  * \r
 307                  * @return The signed value of the {@link Wire}'s bits, where value 0 corresponds with 2^0, value 1 is 2^1 and so on.\r
 308                  * \r
 309                  * @author Fabian Stemmler\r
 310                  */\r
 311                 public long getSignedValue()\r
 312                 {\r
 313                         return Wire.this.getSignedValue();\r
 314                 }\r
 315 \r
 316                 @Override\r
 317                 public String toString()\r
 318                 {\r
 319                         return Wire.this.toString();\r
 320                 }\r
 321 \r
 322                 public void close()\r
 323                 {\r
 324                         inputs.remove(this);\r
 325                         detachEnd(this);\r
 326                         recalculate();\r
 327                 }\r
 328 \r
 329                 public int length()\r
 330                 {\r
 331                         return length;\r
 332                 }\r
 333 \r
 334                 public boolean addObserver(WireObserver ob)\r
 335                 {\r
 336                         return observers.add(ob);\r
 337                 }\r
 338 \r
 339                 public Wire getWire()\r
 340                 {\r
 341                         return Wire.this;\r
 342                 }\r
 343         }\r
 344 \r
 345         public class ReadWriteEnd extends ReadEnd\r
 346         {\r
 347                 private boolean open;\r
 348                 private BitVector inputValues;\r
 349 \r
 350                 private ReadWriteEnd()\r
 351                 {\r
 352                         super();\r
 353                         open = true;\r
 354                         initValues();\r
 355                         registerInput(this);\r
 356                 }\r
 357 \r
 358                 private void initValues()\r
 359                 {\r
 360                         inputValues = U.toVector(length);\r
 361                 }\r
 362 \r
 363                 /**\r
 364                  * Sets the wires values. This takes up time, as specified by the {@link Wire}s travel time.\r
 365                  * \r
 366                  * @param newValues The new values the wires should take on.\r
 367                  * \r
 368                  * @author Fabian Stemmler\r
 369                  */\r
 370                 public void feedSignals(Bit... newValues)\r
 371                 {\r
 372                         feedSignals(BitVector.of(newValues));\r
 373                 }\r
 374 \r
 375                 public void feedSignals(BitVector newValues)\r
 376                 {\r
 377                         if (newValues.length() != length)\r
 378                                 throw new IllegalArgumentException(\r
 379                                                 String.format("Attempted to input %d bits instead of %d bits.", newValues.length(), length));\r
 380                         if (!open)\r
 381                                 throw new RuntimeException("Attempted to write to closed WireArrayEnd.");\r
 382                         Simulation.TIMELINE.addEvent(e -> setValues(newValues), travelTime);\r
 383                 }\r
 384 \r
 385                 /**\r
 386                  * Sets values of a subarray of wires. This takes up time, as specified by the {@link Wire}s travel time.\r
 387                  * \r
 388                  * @param bitVector   The new values the wires should take on.\r
 389                  * @param startingBit The first index of the subarray of wires.\r
 390                  * \r
 391                  * @author Fabian Stemmler\r
 392                  */\r
 393                 public void feedSignals(int startingBit, BitVector bitVector)\r
 394                 {\r
 395                         if (!open)\r
 396                                 throw new RuntimeException("Attempted to write to closed WireArrayEnd.");\r
 397                         Simulation.TIMELINE.addEvent(e -> setValues(startingBit, bitVector), travelTime);\r
 398                 }\r
 399 \r
 400                 private void setValues(int startingBit, BitVector newValues)\r
 401                 {\r
 402                         // index check covered in equals\r
 403                         if (!inputValues.equalsWithOffset(newValues, startingBit))\r
 404                         {\r
 405                                 Bit[] vals = inputValues.getBits();\r
 406                                 System.arraycopy(newValues.getBits(), 0, vals, startingBit, newValues.length());\r
 407                                 inputValues = BitVector.of(vals);\r
 408                                 Wire.this.recalculate();\r
 409                         }\r
 410                 }\r
 411 \r
 412                 private void setValues(BitVector newValues)\r
 413                 {\r
 414                         if (inputValues.equals(newValues))\r
 415                                 return;\r
 416                         inputValues = newValues;\r
 417                         Wire.this.recalculate();\r
 418                 }\r
 419 \r
 420                 /**\r
 421                  * @return The value (of bit 0) the {@link ReadEnd} is currently feeding into the associated {@link Wire}.\r
 422                  */\r
 423                 public Bit getInputValue()\r
 424                 {\r
 425                         return getInputValue(0);\r
 426                 }\r
 427 \r
 428                 /**\r
 429                  * @return The value which the {@link ReadEnd} is currently feeding into the associated {@link Wire} at the indexed {@link Bit}.\r
 430                  */\r
 431                 public Bit getInputValue(int index)\r
 432                 {\r
 433                         return inputValues.getBit(index);\r
 434                 }\r
 435 \r
 436                 /**\r
 437                  * @return A copy (safe to modify) of the values the {@link ReadEnd} is currently feeding into the associated {@link Wire}.\r
 438                  */\r
 439                 public BitVector getInputValues()\r
 440                 {\r
 441                         return getInputValues(0, length);\r
 442                 }\r
 443 \r
 444                 public BitVector getInputValues(int start, int end)\r
 445                 {\r
 446                         return inputValues.subVector(start, end);\r
 447                 }\r
 448 \r
 449                 /**\r
 450                  * {@link ReadEnd} now feeds Z into the associated {@link Wire}.\r
 451                  */\r
 452                 public void clearSignals()\r
 453                 {\r
 454                         feedSignals(Z.toVector(length));\r
 455                 }\r
 456 \r
 457                 public BitVector wireValuesExcludingMe()\r
 458                 {\r
 459                         BitVectorMutator mutator = BitVectorMutator.empty();\r
 460                         for (ReadWriteEnd wireEnd : inputs)\r
 461                         {\r
 462                                 if (wireEnd == this)\r
 463                                         continue;\r
 464                                 mutator.join(wireEnd.inputValues);\r
 465                         }\r
 466                         return mutator.get();\r
 467                 }\r
 468 \r
 469                 @Override\r
 470                 public String toString()\r
 471                 {\r
 472                         return inputValues.toString();\r
 473                 }\r
 474         }\r
 475 \r
 476         @Override\r
 477         public String toString()\r
 478         {\r
 479                 return String.format("wire 0x%08x value: %s inputs: %s", hashCode(), values, inputs);\r
 480                 // Arrays.toString(values), inputs.stream().map(i -> Arrays.toString(i.inputValues)).reduce((s1, s2) -> s1 + s2)\r
 481         }\r
 482 \r
 483         public static ReadEnd[] extractEnds(Wire[] w)\r
 484         {\r
 485                 ReadEnd[] inputs = new ReadEnd[w.length];\r
 486                 for (int i = 0; i < w.length; i++)\r
 487                         inputs[i] = w[i].createEnd();\r
 488                 return inputs;\r
 489         }\r
 490 }