ship: Stack

== Ports ===========================================================
data  in:   push
data  out:  pop

== Constants ========================================================

== TeX ==============================================================
A stack ship with capacity for at least 32 elements.

Push operations are executed as soon as an inbound datum is {\tt
deliver}ed on the {\tt push} port.  Completion of a push can be
confirmed by sending a {\tt notify} token from the {\tt push} port.

Pop operations are executed no earlier than the time at which the {\tt
pop} port attempts to {\tt take} data from the ship.

When the stack becomes full, it will simply not process any new {\tt
push} operations.  When the stack becomes empty, it will simply not
process any new {\tt pop} operations.

== Fleeterpreter ====================================================
    private ArrayList<Long> stack = new ArrayList<Long>();
    public void service() {
        if (box_push.dataReadyForShip() && stack.size()<32) {
            stack.add(box_push.removeDataForShip());
        }
        if (box_pop.readyForDataFromShip() && stack.size() > 0) {
            box_pop.addDataFromShip(stack.get(stack.size()-1));
            stack.remove(stack.size()-1);
        }
    }

== FleetSim ==============================================================
== FPGA ==============================================================
/* FIXME: inefficient */
  reg    [(`DATAWIDTH-1):0] mem [4:0];
  reg    [5:0]              depth;
  reg    skip;
  initial depth = 0;

  always @(posedge clk) begin
    skip = 0;
    if (depth > 0) begin
      `onwrite(pop_r, pop_a)
        if (depth > 1) begin
          pop_d <= mem[depth-2];
        end
        depth <= depth - 1;
        skip = 1;
      end
    end
    if (!skip && depth < 32) begin
      `onread(push_r, push_a)
        pop_d      <= push_d;
        mem[depth] <= push_d;
        depth      <= depth + 1;
      end
    end
  end


== Test ====================================================
#ship stack : Stack
#ship debug : Debug

#expect 4
#expect 3
#expect 2
#expect 1
#expect 0

debug.in:  [*] take, deliver;
stack.push: [5] take, deliver; notify stack.pop;

stack.pop: wait; [*] take, sendto debug.in;

0: sendto stack.push;
1: sendto stack.push;
2: sendto stack.push;
3: sendto stack.push;
4: sendto stack.push;




== Contributors =========================================================
Adam Megacz <megacz@cs.berkeley.edu>