Skip to content
Snippets Groups Projects
Commit b4c4b793 authored by Oliver Breitwieser's avatar Oliver Breitwieser
Browse files

Rework connection interface

* As discussed on 2020-04-07 after the Softie's meeting (ECM, YS, PSP,
  CM, OJB), we want to have a streamlined connection interfaces for all
  the possible ways we turn FPGA words into other FPGA words in
  hardware.

* C++-API: Split old Connection objects into two parts:
  * The connection object that the user can only create and destroy but
    which holds state necessary for communication with the backend (hw,
    CoSim, QuiggelyClient, etc) and allows some state to be set.
  * Introduce hxcomm/common/stream.h:
    * The Stream-object featuring a uniform interface handling how to
      feed and read words to/from the backend.
    * The interface is defined via templated `Stream`-class that has to
      be befriended in the corresponding connection implementations
    * The Stream-interface is verified at compile time via the
      Streamable helper-struct.

* Move `execute_words` from fisch as more generic
  `execute_messages`-function that is the entry point for all upper
  layers when communcating with backends.
  * Overloading is possible by fully or partially-specializing the
    detail::ExecutorMessages-helper struct's operator() method (not
    needed once partial function specialization arrives, so never)
  * default implementation in common namespace by adding explicit
    `send_halt_message_type` to ConnectionParameter template argument

* Rework hxcomm/common/{arq,sim}connection.{h,tcc} to use the new Stream
  interface.

* Update all tests to use streams for interacting with the hardware.

* Rename init_parameters_t -> init_parameters_type to be consistent
  (they will be used by quiggeldy but that change is not merged -> no
  API break)

* Provide get_connection_from_env-function that returns a connection
  variant over all possible connections (and is used in pyhxcomm, see
  below).

* Introduce seperate `pyhxcomm`-namespace that is private to hxcomm and
  only to be accessed from Python. It adds convenience context-wrappers
  for connections ensuring connections get closed upon exiting contexts
  in Python
  * pyhxcomm::Managed<Connection> provides enter/exit-methods
  * enter() returns pyhxcom::Handle<Connection> holding the connection
  * if Handle<Connection> gets destroyed, connection gets freed (i.e.
    disconnected)
  * Managed<Connection> also holds a weak-ptr to the returned
    ConnectionHandle object and disconnects the Handle upon exit()-ing
  * Expose union over all Connections as `pyhxcomm_vx.ConnectionHandle`
    that can be used in type annotations in Python.
  * Expose special context manager `pyhxcomm_vx.ManagedConnection` that
    automatically creates a new connection from the environment and
    returns `ConnectionHandle` (which is a concrete `<Connection>Handle`
    in python rather than the cumbersome variant type).

* Introduce hxcomm::visit_connection that allows for applying operations
  on connections wrapped in Handle-objects such as variants for hxcomm
  and pyhxcomm::ConnectionHandles. It is used in
  hxcomm::execute_messages as well as stadls::run-pybind11 bindings.
  * Functions templated over connections can be easily specialized for
    all wrapped connections via:
    * `ConnectionIsPlainGuard<Connection> = 0`
    * `ConnectionIsWrappedGuard<Connection> = 0`
  * Another possibility is to perform compile time checks using
    `ConnectionIsPlain<Connection>::value` (see `run`-implementation in
    haldls for example).

* Add `static char const name[]` attributes for all connection for more
  informative logging.

Depends-On: 10346,10335,10703,10978,11027

Change-Id: I3ff901db53a5cb94a1faa50b18dc36786246f389
parent f10fec69
No related branches found
No related tags found
No related merge requests found
Showing
with 639 additions and 84 deletions
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment