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