stubbed out mkBus for now - awaits full implementation

bs/BusTypes.bs

@@ -1,4 +1,5 @@
 package BusTypes(
+    Bus(..),
     MkClientTagType,
     BusClient(..), BusServer(..),
     BusRequest(..), BusResponse(..),
@@ -44,7 +45,7 @@ type WriteResponse = Either BusError ()
 
 data BusRequest
   = BusReadRequest      ReadRequest
-  | WriteReadRequest    WriteRequest
+  | BusWriteRequest     WriteRequest
   deriving (Bits, Eq, FShow)
 
 data BusResponse
@@ -52,47 +53,44 @@ data BusResponse
   | BusWriteResponse    WriteResponse
   deriving (Bits, Eq, FShow)
 
--- # BusClient.dequeueRequest
---   * The Bus arbiter will call the Bus Client's request method if it is
---     the Bus Client's turn to make a request, or if another client forfits
---     its turn.
---   * The BusClient must guard its request method such that calling its
---     request method is only valid when the BusClient has a request to make.
---   * This has implications about for the implementor of BusClient,
---     namely, that it should hold its request until it's request method
---     gets called. The arbiter tags the request so that the client can
---     later correctly correlate the response.
---   * Although the tag is technically passed in as an argument from the
---     arbiter to the client's request method, given that methods are
---     atomic in Bluespec, this is effectively equivalent to tagging the
---     transaction from the client's perspective. Thus, the client must
---     take care to appropiately store the tag.
--- # BusClient.enqueueResponse
---   * From the client's perspective, the response should not be called
---     by the arbiter until the client is ready to accept the response.
---     In other words, the response method should be guarded by the client.
+-- # BusClient.submitRequest
+--   * The bus client calls the `submitRequest` method of the `BusClient` interface
+--     with the `BusRequest` it wishes to submit and immediately recieves back
+--     a transaction-duration-unqiue tag that it can later correlate with the
+--     returned response should responses arrive out of order(OOO). OOO can
+--     happen if a bus server is is able to process bus requests faster than
+--     other bus servers for example.
+-- # BusClient.consumeResponse
+--   * The bus client is able to consume a response when a response is available.
+--     Responses are tagged with the tag given to bus client when it called
+--     `submitRequest`
 interface (BusClient :: # -> *) inFlightTransactions =
-  dequeueRequest  :: MkTagType inFlightTransactions
-                  -> ActionValue BusRequest
-  enqueueResponse :: (BusResponse, MkTagType inFlightTransactions)
+  submitRequest   :: BusRequest
+                  -> ActionValue (MkTagType inFlightTransactions)
+  consumeResponse :: ActionValue (BusResponse, MkTagType inFlightTransactions)
+
+-- # BusServer.consumeRequest
+--   * The bus server calls the `consumeRequest` method of the `BusServer` interface
+--     to retrieve a pending bus request initiated by a client. It immediately
+--     receives a tuple containing a transaction-duration-unique tag
+--     (associated with the original request) and the `BusRequest` itself. This
+--     tag is used to track the transaction and correlate it with the eventual
+--     response.
+-- # BusServer.submitResponse
+--   * The bus server calls the `submitResponse` method to send a `BusResponse`
+--     back to the originating client. The method takes a tuple containing:
+--     - A client tag (of type `MkClientTagType numClients`) identifying the
+--       client that submitted the request.
+--     - The `BusResponse` containing the result of the request (either a read
+--       or write response).
+--     - The transaction tag (of type `transactionTagType`) that matches the tag
+--       received from `consumeRequest`, ensuring the response is correctly
+--       associated with the original request.
+interface (BusServer :: # -> # -> *) inFlightTransactions numClients =
+  consumeRequest  :: ActionValue (MkTagType inFlightTransactions, BusRequest)
+  submitResponse  :: (MkClientTagType numClients, BusResponse, transactionTagType)
                   -> Action
 
--- # BusServer.dequeueResponse
---   * If the arbiter is able to successfully call `dequeueResponse`, then
---     the BusServer's internal logic must update such that it understands
---     the response has been handed off.
--- # BusServer.peekClientTagDestination
---   * The arbiter looks at (peekClientTagDestination :: MkClientTagType) to
---     determine whether or not it is currently safe whether to dequeue the
---     response as well as where to route the response should it dequeue the
---     response.
---   * `peekClientTagDestination` should be guarded on whether or not there is
---     a valid response available.
-interface (BusServer :: # -> # -> *) inFlightTransactions numClients =
-  enqueueRequest  :: (MkTagType inFlightTransactions, BusRequest)
-                  -> Action
-  dequeueResponse :: ActionValue (
-                      MkClientTagType numClients,
-                      BusResponse, transactionTagType
-                      )
-  peekClientTagDestination :: MkClientTagType numClients
+interface (Bus :: # -> # -> # -> *) inFlightTransactions numClients numServers =
+  clients :: Vector numClients (BusClient inFlightTransactions)
+  servers :: Vector numServers (BusServer inFlightTransactions numClients)