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

   1 package era.mi.logic.wires;
   2
   3 import java.util.ArrayList;
   4 import java.util.Arrays;
   5 import java.util.Iterator;
   6 import java.util.List;
   7
   8 import era.mi.logic.Bit;
   9 import era.mi.logic.Simulation;
  10 import era.mi.logic.Util;
  11
  12 /**
  13  * Represents an array of wires that can store n bits of information.
  14  *
  15  * @author Fabian Stemmler
  16  *
  17  */
  18 public class WireArray
  19 {
  20         private Bit[] values;
  21         public final int travelTime;
  22         private List<WireArrayObserver> observers = new ArrayList<WireArrayObserver>();
  23         public final int length;
  24         private List<WireArrayInput> inputs = new ArrayList<WireArrayInput>();
  25
  26         public WireArray(int length, int travelTime)
  27         {
  28                 if (length < 1)
  29                         throw new IllegalArgumentException(String.format("Tried to create an array of wires with length %d, but a length of less than 1 makes no sense.", length));
  30                 this.length = length;
  31                 this.travelTime = travelTime;
  32                 initValues();
  33         }
  34
  35         private void initValues()
  36         {
  37                 values = Bit.Z.makeArray(length);
  38         }
  39
  40         private void recalculateSingleInput()
  41         {
  42                 WireArrayInput input = inputs.get(0);
  43                 if (!Arrays.equals(input.getValues(), values))
  44                 {
  45                         Bit[] oldValues = values.clone();
  46                         System.arraycopy(input.getValues(), 0, values, 0, length);
  47                         notifyObservers(oldValues);
  48                 }
  49         }
  50
  51         private void recalculateMultipleInputs()
  52         {
  53                 Iterator<WireArrayInput> it = inputs.iterator();
  54                 Bit[] newValues = it.next().inputValues.clone();
  55
  56                 while (it.hasNext())
  57                 {
  58                         WireArrayInput input = it.next();
  59                         Bit[] bits = input.getValues();
  60                         for (int i = 0; i < length; i++)
  61                         {
  62                                 if (Bit.Z.equals(bits[i]) || newValues[i].equals(bits[i]))
  63                                         continue;
  64                                 else if (Bit.Z.equals(newValues[i]))
  65                                         newValues[i] = bits[i];
  66                                 else
  67                                         newValues[i] = Bit.X;
  68                         }
  69                 }
  70
  71                 if (!Arrays.equals(newValues, values))
  72                 {
  73                         Bit[] oldValues = values;
  74                         values = newValues;
  75                         notifyObservers(oldValues);
  76                 }
  77         }
  78
  79         private void recalculate()
  80         {
  81                 switch (inputs.size())
  82                 {
  83                 case 0:
  84                         return;
  85                 case 1:
  86                         recalculateSingleInput();
  87                         break;
  88                 default:
  89                         recalculateMultipleInputs();
  90                 }
  91         }
  92
  93         /**
  94          * The WireArray is interpreted as an unsigned integer with n bits.
  95          *
  96          * @return <code>true</code> if all bits are either <code>Bit.ONE</code> or
  97          *         <code>Bit.ZERO</code> (they do not all have to have the same value),
  98          *         not <code>Bit.X</code> or <code>Bit.Z</code>. <code>false</code> is
  99          *         returned otherwise.
 100          *
 101          * @author Fabian Stemmler
 102          */
 103         public boolean hasNumericValue()
 104         {
 105                 for (Bit b : values)
 106                 {
 107                         if (b != Bit.ZERO && b != Bit.ONE)
 108                                 return false;
 109                 }
 110                 return true;
 111         }
 112
 113         /**
 114          * The WireArray is interpreted as an unsigned integer with n bits.
 115          *
 116          * @return The unsigned value of the {@link WireArray}'s bits, where value 0
 117          *         corresponds with 2^0, value 1 is 2^1 and so on.
 118          *
 119          * @author Fabian Stemmler
 120          */
 121         public long getUnsignedValue()
 122         {
 123                 long val = 0;
 124                 long mask = 1;
 125                 for (int i = 0; i < length; i++)
 126                 {
 127                         switch (values[i])
 128                         {
 129                         default:
 130                         case Z:
 131                         case X:
 132                                 return 0; // TODO: Proper handling for getUnsignedValue(), if not all bits are 1 or 0;
 133                         // Random number?
 134                         case ONE:
 135                                 val |= mask;
 136                                 break;
 137                         case ZERO:
 138                         }
 139                         mask = mask << 1;
 140                 }
 141                 return val;
 142         }
 143
 144         /**
 145          * The WireArray is interpreted as a signed integer with n bits.
 146          *
 147          * @return The signed value of the {@link WireArray}'s bits, where value 0
 148          *         corresponds with 2^0, value 1 is 2^1 and so on.
 149          *
 150          * @author Fabian Stemmler
 151          */
 152         public long getSignedValue()
 153         {
 154                 long val = getUnsignedValue();
 155                 long mask = 1 << (length - 1);
 156                 if ((mask & val) != 0)
 157                 {
 158                         int shifts = 64 - length;
 159                         return (val << shifts) >> shifts;
 160                 }
 161                 return val;
 162         }
 163
 164         /**
 165          * Included for convenient use on {@link WireArray}s of length 1.
 166          *
 167          * @return The value of bit 0.
 168          *
 169          * @author Fabian Stemmler
 170          */
 171         public Bit getValue()
 172         {
 173                 return getValue(0);
 174         }
 175
 176         /**
 177          *
 178          * @param index Index of the requested bit.
 179          * @return The value of the indexed bit.
 180          *
 181          * @author Fabian Stemmler
 182          */
 183         public Bit getValue(int index)
 184         {
 185                 return values[index];
 186         }
 187
 188         public Bit[] getValues(int start, int end)
 189         {
 190                 int length = end - start;
 191                 Bit[] bits = new Bit[length];
 192                 System.arraycopy(values, start, bits, 0, length);
 193                 return bits;
 194         }
 195
 196         /**
 197          * @return An array of length n containing the values of the n bits in the
 198          *         {@link WireArray}. Can be safely modified.
 199          *
 200          * @author Fabian Stemmler
 201          */
 202         public Bit[] getValues()
 203         {
 204                 return values.clone();
 205         }
 206
 207         /**
 208          * Adds an {@link WireArrayObserver}, who will be notified when the value of the
 209          * {@link WireArray} is updated.
 210          *
 211          * @param ob The {@link WireArrayObserver} to be notified of changes.
 212          * @return true if the given {@link WireArrayObserver} was not already
 213          *         registered, false otherwise
 214          *
 215          * @author Fabian Stemmler
 216          */
 217         public boolean addObserver(WireArrayObserver ob)
 218         {
 219                 return observers.add(ob);
 220         }
 221
 222         private void notifyObservers(Bit[] oldValues)
 223         {
 224                 for (WireArrayObserver o : observers)
 225                         o.update(this, oldValues);
 226         }
 227
 228         /**
 229          * Create and register a {@link WireArrayInput} object, which is tied to this
 230          * {@link WireArray}.
 231          */
 232         public WireArrayInput createInput()
 233         {
 234                 return new WireArrayInput(this);
 235         }
 236
 237         private void registerInput(WireArrayInput toRegister)
 238         {
 239                 inputs.add(toRegister);
 240         }
 241
 242         /**
 243          * A {@link WireArrayInput} feeds a constant signal into the {@link WireArray}
 244          * it is tied to. The combination of all inputs determines the
 245          * {@link WireArray}s final value. X dominates all other inputs Z does not
 246          * affect the final value, unless there are no other inputs than Z 0 and 1 turn
 247          * into X when they are mixed
 248          *
 249          * @author Fabian Stemmler
 250          */
 251         public class WireArrayInput
 252         {
 253                 public final WireArray owner;
 254                 private Bit[] inputValues;
 255
 256                 private WireArrayInput(WireArray owner)
 257                 {
 258                         super();
 259                         this.owner = owner;
 260                         initValues();
 261                         owner.registerInput(this);
 262                 }
 263
 264                 private void initValues()
 265                 {
 266                         inputValues = Bit.Z.makeArray(length);
 267                 }
 268
 269                 /**
 270                  * Sets the wires values. This takes up time, as specified by the
 271                  * {@link WireArray}s travel time.
 272                  *
 273                  * @param newValues The new values the wires should take on.
 274                  *
 275                  * @author Fabian Stemmler
 276                  */
 277                 public void feedSignals(Bit... newValues)
 278                 {
 279                         if (newValues.length == length)
 280                         {
 281                                 feedSignals(0, newValues);
 282                         } else
 283                                 throw new IllegalArgumentException(String.format("Attempted to input %o bits instead of %o bits.", newValues.length, length));
 284                 }
 285
 286                 /**
 287                  * Sets values of a subarray of wires. This takes up time, as specified by the
 288                  * {@link WireArray}s travel time.
 289                  *
 290                  * @param newValues   The new values the wires should take on.
 291                  * @param startingBit The first index of the subarray of wires.
 292                  *
 293                  * @author Fabian Stemmler
 294                  */
 295                 public void feedSignals(int startingBit, Bit... newValues)
 296                 {
 297                         Simulation.TIMELINE.addEvent((e) -> setValues(startingBit, newValues), travelTime);
 298                 }
 299
 300                 private void setValues(int startingBit, Bit... newValues)
 301                 {
 302                         int exclLastIndex = startingBit + newValues.length;
 303                         if (length < exclLastIndex)
 304                                 throw new ArrayIndexOutOfBoundsException(String.format("Attempted to input bits from index %o to %o when there are only %o wires.", startingBit, exclLastIndex - 1, length));
 305                         if (!Arrays.equals(inputValues, startingBit, exclLastIndex, newValues, 0, newValues.length))
 306                         {
 307                                 System.arraycopy(newValues, 0, inputValues, startingBit, newValues.length);
 308                                 owner.recalculate();
 309                         }
 310                 }
 311
 312                 /**
 313                  * Returns a copy (safe to modify) of the values the {@link WireArrayInput} is currently feeding into the associated {@link WireArray}.
 314                  */
 315                 public Bit[] getValues()
 316                 {
 317                         return inputValues.clone();
 318                 }
 319
 320                 /**
 321                  * {@link WireArrayInput} now feeds Z into the associated {@link WireArray}.
 322                  */
 323                 public void clearSignals()
 324                 {
 325                         feedSignals(Bit.Z.makeArray(length));
 326                 }
 327
 328                 public Bit[] wireValuesExcludingMe()
 329                 {
 330                         Bit[] bits = Bit.Z.makeArray(length);
 331                         for (WireArrayInput wai : inputs)
 332                         {
 333                                 if(wai == this)
 334                                         continue;
 335                                 Util.combineInto(bits, wai.getValues());
 336                         }
 337                         return bits;
 338                 }
 339
 340                 @Override
 341                 public String toString()
 342                 {
 343                         return Arrays.toString(inputValues);
 344                 }
 345         }
 346
 347         @Override
 348         public String toString()
 349         {
 350                 return String.format("wire 0x%08x value: %s inputs: %s", hashCode(), Arrays.toString(values), inputs);
 351         }
 352
 353         public static WireArrayInput[] extractInputs(WireArray[] w)
 354         {
 355                 WireArrayInput[] inputs = new WireArrayInput[w.length];
 356                 for (int i = 0; i < w.length; i++)
 357                         inputs[i] = w[i].createInput();
 358                 return inputs;
 359         }
 360 }