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

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