package MemArbiter;

import Connectable::*;
import Vector::*;

export MemArbiterOp(..);
export MemArbiterServer(..);
export MemArbiter(..), mkPriorityMemArbiter, mkRoundRobinMemArbiter;

// A MemArbiterOp is an operation that a client is seeking permission
// to perform.
typedef struct {
   Bool write;
   addr addr;
} MemArbiterOp#(type addr) deriving (Bits, Eq, FShow);

// mem_ops_conflict reports whether memory accesses a and b would
// cause undefined behavior if they proceed simultaneously.
function Bool mem_ops_conflict(Maybe#(MemArbiterOp#(addr)) a, Maybe#(MemArbiterOp#(addr)) b)
   provisos(Eq#(addr));

   if (a matches tagged Valid .ar &&& b matches tagged Valid .br &&& ar.addr == br.addr)
      return ar.write || br.write;
   else
      return False;
endfunction

// A MemArbiterServer receives requests and emits grants.
(* always_ready *)
interface MemArbiterServer#(type addr);
   method Action request(MemArbiterOp#(addr) req);
   method Bool grant();
endinterface

// A MemArbiter manages concurrent access to a memory port.
interface MemArbiter#(numeric type num_clients, type addr);
   // ports allow clients to request memory access.
   interface Vector#(num_clients, MemArbiterServer#(addr)) ports;

   // granted_port returns the index in ports of the client that is
   // being granted its request.
   method UInt#(TLog#(num_clients)) granted_port();

   // The following methods are to support arbiter chaining.
   //
   // Suppose you're arbitrating access to a dual-port memory.
   // Typically, such a memory specifies that if one port is writing
   // to an address, the other must not concurrently read or write
   // that same address. This means the arbiters attached to each
   // memory port must cooperate to avoid simultaneously granting
   // conflicting requests from their clients.
   //
   // conflict_in supplies an already granted operation that this
   // arbiter must avoid conflicting with. conflict_out emits the
   // operation that the arbiter is granting, if any.
   //
   // mkConnection(firstArbiter, secondArbiter) gives conflict
   // priority to firstArbiter. That is, secondArbiter only grants
   // requests that don't conflict with grants made by firstArbiter.
   (* always_ready *)
   method Action conflict_in(MemArbiterOp#(addr) conflict);
   method MemArbiterOp#(addr) conflict_out();
endinterface

instance Connectable#(MemArbiter#(m, addr), MemArbiter#(n, addr));
   module mkConnection(MemArbiter#(m, addr) a, MemArbiter#(n, addr) b, Empty ifc);
      mkConnection(a.conflict_out, b.conflict_in);
   endmodule
endinstance

// mkPriorityMemArbiter returns a MemArbiter that gives priority to
// lower numbered ports.
module mkPriorityMemArbiter(MemArbiter#(num_clients, addr))
   provisos (Bits#(addr, _),
             Eq#(addr),
             Min#(num_clients, 1, 1),
             Alias#(client_idx, UInt#(TLog#(num_clients))));

   Vector#(num_clients, RWire#(MemArbiterOp#(addr))) reqs <- replicateM(mkRWire());
   Wire#(Vector#(num_clients, Bool)) grants <- mkBypassWire();

   RWire#(MemArbiterOp#(addr)) conflict_op <- mkRWire();
   RWire#(client_idx) granted_idx <- mkRWire();

   (* no_implicit_conditions, fire_when_enabled *)
   rule grant_requests;
      Vector#(num_clients, Bool) grant = replicate(False);
      Bool done = False;

      for (Integer i=0; i<valueOf(num_clients); i=i+1) begin
         if (reqs[i].wget() matches tagged Valid .req &&&
             !mem_ops_conflict(conflict_op.wget(), reqs[i].wget()) &&&
             !done) begin
                       done = True;
                       grant[i] = True;
                       granted_idx.wset(fromInteger(i));
                    end
      end

      grants <= grant;
   endrule

   Vector#(num_clients, MemArbiterServer#(addr)) _ifcs = newVector();
   for (Integer i=0; i<valueOf(num_clients); i=i+1)
      _ifcs[i] = (interface MemArbiterServer#(addr);
                     method request = reqs[i].wset;
                     method grant = grants[i];
                  endinterface);

   interface ports = _ifcs;
   method client_idx granted_port() if (granted_idx.wget() matches tagged Valid .idx);
      return idx;
   endmethod
   method MemArbiterOp#(addr) conflict_out() if (granted_idx.wget() matches tagged Valid .idx &&&
                                                 reqs[idx].wget() matches tagged Valid .op);
      return op;
   endmethod
   method conflict_in = conflict_op.wset;
endmodule

typedef struct {
   Vector#(n, Bool) grant_vec;
   Maybe#(UInt#(TLog#(n))) granted_idx;
} GrantResult#(numeric type n, type addr) deriving (Bits, Eq, FShow);

// select_grant computes which one entry of requests should be
// granted. Priority order is descending starting from
// requests[hipri].
function GrantResult#(n, addr) select_grant(Vector#(n, Maybe#(MemArbiterOp#(addr))) requests,
                                            client_idx hipri,
                                            Maybe#(MemArbiterOp#(addr)) conflict)
   provisos (Eq#(addr),
             Alias#(client_idx, UInt#(TLog#(n))));

   function onehot(idx);
      let ret = replicate(False);
      ret[idx] = True;
      return ret;
   endfunction

   function GrantResult#(n, addr) do_fold(GrantResult#(n, addr) acc,
                                          Tuple2#(client_idx,
                                                  Maybe#(MemArbiterOp#(addr))) next);
      match {.idx, .mreq} = next;
      if (mreq matches tagged Valid .req &&&
          acc.granted_idx matches tagged Invalid &&&
          !mem_ops_conflict(conflict, mreq))
         return GrantResult{
            grant_vec: onehot(idx),
            granted_idx: tagged Valid idx
         };
      else
         // Previous grant won, not requesting, or request not satisfiable.
         return acc;
   endfunction

   let in = zip(map(fromInteger, genVector()), requests);
   let rot = rotateBy(in, fromInteger(valueOf(n)-1)-hipri+1);
   let seed = GrantResult{
      grant_vec: replicate(False),
      granted_idx: tagged Invalid
   };
   return foldl(do_fold, seed, rot);
endfunction

module mkRoundRobinMemArbiter(MemArbiter#(num_clients, addr))
   provisos (Bits#(addr, _),
             Eq#(addr),
             Min#(num_clients, 1, 1),
             Alias#(client_idx, UInt#(TLog#(num_clients))));

   Vector#(num_clients, RWire#(MemArbiterOp#(addr))) reqs <- replicateM(mkRWire);
   Wire#(Vector#(num_clients, Bool)) grants <- mkBypassWire();

   RWire#(MemArbiterOp#(addr)) conflict_op <- mkRWire();
   RWire#(client_idx) granted_idx_out <- mkRWire();

   // high_prio is the index of the client that should be first in
   // line to receive access. Every time we grant access to a client,
   // the one after that in sequence becomes high_prio in the next
   // round.
   Reg#(client_idx) high_prio <- mkReg(0);

   function Maybe#(_t) get_mreq(RWire#(_t) w);
      return w.wget();
   endfunction

   rule grant;
      let in = map(get_mreq, reqs);
      let res = select_grant(in, high_prio, conflict_op.wget());

      grants <= res.grant_vec;
      if (res.granted_idx matches tagged Valid .idx) begin
         granted_idx_out.wset(idx);
         high_prio <= validValue(findElem(True, rotateR(res.grant_vec)));
      end
   endrule

   Vector#(num_clients, MemArbiterServer#(addr)) _ifcs = newVector();
   for (Integer i=0; i<valueOf(num_clients); i=i+1)
      _ifcs[i] = (interface MemArbiterServer#(addr);
                     method request = reqs[i].wset;
                     method grant = grants[i];
                  endinterface);

   interface ports = _ifcs;
   method client_idx granted_port() if (granted_idx_out.wget() matches tagged Valid .idx);
      return idx;
   endmethod
   method MemArbiterOp#(addr) conflict_out() if (granted_idx_out.wget() matches tagged Valid .idx &&&
                                                reqs[idx].wget() matches tagged Valid .op);
      return op;
   endmethod
   method conflict_in = conflict_op.wset;
endmodule

endpackage