package edu.berkeley.fleet.api;
-import edu.berkeley.fleet.doc.*;
import java.io.*;
import java.util.*;
+/**
+ * An instance of Fleet; each Fleet consists of a collection of
+ * <tt>Ship</tt>s.
+ *
+ * <p><b>Note about instruction representation:</b> it is very
+ * important to understand that the binary representation of an
+ * instruction includes a path from the dock which will
+ * <i>dispatch</i> the instruction to the dock which will
+ * <i>execute</i> the instruction. Therefore, an instruction cannot
+ * be converted <i>to</i> binary form without supplying a
+ * <i>dispatching dock</i> so the necessary path can be computed.
+ * <b>Moreover:</b> because a given string of bits uniquely describes
+ * a path only if given along with a starting point, instructions
+ * cannot be converted <i>from</i> binary format without knowing the
+ * dispatch dock from which they are meant to be dispatched. <i>This
+ * is why the {@link readInstruction} and {@link writeInstruction}
+ * methods take a "<tt>dispatchFrom</tt>" argument.</i>
+ */
public abstract class Fleet implements Iterable<Ship> {
- /** read a machine-formatted instruction from a file (into a Java object) */
- public abstract Instruction readInstruction(DataInputStream is) throws IOException;
+ public abstract Iterator<Ship> iterator();
- /** write a machine-formatted instruction to a file (from a Java object) */
- public abstract void writeInstruction(DataOutputStream os, Instruction instr) throws IOException;
+ /** A ship is uniquely identified by its type (a string) and its ordinal; for example, Fifo[7]. */
+ public abstract Ship getShip(String type, int ordinal);
- /** ships must be returned in the same order every time -- ordering may be significant */
- public abstract Iterator<Ship> iterator();
+ /** the natural word width of this machine */
+ public abstract int getWordWidth();
- /**
- * Compute the value that should go in the MACHINE-addressed
- * "offset" field of a literal given BYTE-addressed origin and
- * target
- */
- public abstract int computeOffset(int origin, int target);
+ /** the width of the immediate field in the "shift data latch" instruction */
+ public abstract int getShiftWidth();
- /**
- * Compute the value that should go in the "offset" field of a
- * literal given BYTE-addressed origin and MACHINE-addressed
- * target
- */
- public abstract int computeTarget(int origin, int offset);
-
- /** if possible, run the given code and create a FleetProcess */
- public FleetProcess run(byte[] code) {
- throw new RuntimeException("class " + this.getClass().getName() + " does not implement method run()");
- }
+ /** the width of the immediate field in the "set data latch" instruction */
+ public abstract int getSetWidth();
- /** extract the portion of ShipDescription which is specific to this fleet and generate any source code necessary */
- public void expand(ShipDescription sd) {
- throw new RuntimeException("class " + this.getClass().getName() + " does not implement method expand()");
- }
+ /** FIXME: this will soon become a property of individual memories rather than the entire Fleet */
+ public abstract int getMaxCodeBagSize();
+ /** FIXME: this will soon become a property of individual memories rather than the entire Fleet */
+ public abstract BitVector makeCodeBagDescriptor(long offset, long length);
+
/**
- * This interface marks Fleets which can create ships on the fly, like the fleeterpreter;
- * if available, the parser will use this interface to create ships out of #ship definitions.
+ * Encodes an instruction as a BitVector
+ * @instruction The instruction to encode
+ * @dispatchFrom The dock from which the instruction being written is to be dispatched (required for encoding)
*/
- public static interface WithDynamicShips {
- public Ship createShip(String shiptype, String shipname);
- }
+ public abstract BitVector encodeInstruction(Instruction instruction, Dock dispatchFrom);
+
+ /**
+ * Decodes an instruction from a BitVector
+ * @instruction The instruction to decode
+ * @dispatchFrom The dock from which the instructions being read are to be dispatched (required for decoding)
+ */
+ public abstract Instruction decodeInstruction(BitVector instruction, Dock dispatchFrom);
-}
\ No newline at end of file
+ /** If supported, run the given code and create a FleetProcess to interact with it. */
+ public FleetProcess run(Instruction[] program) {
+ throw new RuntimeException("class " + this.getClass().getName() + " does not implement method run()");
+ }
+}
projects / fleet.git / blobdiff