common_cells

// Copyright 2021 ETH Zurich and University of Bologna.
//
// Copyright and related rights are licensed under the Solderpad Hardware
// License, Version 0.51 (the "License"); you may not use this file except in
// compliance with the License. You may obtain a copy of the License at
// http://solderpad.org/licenses/SHL-0.51. Unless required by applicable law
// or agreed to in writing, software, hardware and materials distributed under
// this License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
// CONDITIONS OF ANY KIND, either express or implied. See the License for the
// specific language governing permissions and limitations under the License.
//
// Authors:
// - Manuel Eggimann <meggimann@iis.ee.ethz.ch>
// - Philippe Sauter <phsauter@iis.ee.ethz.ch> (formalization and stage cleanup)
//
// Description: CDC Clear Signaling Synchronization
// Coordinate clear and isolate sequencing between two CDC clock domains so
// one-sided reset or clear requests do not break the protected CDC protocol.
//
// Detailed Description:
// This module is mainly used internally to synchronize the clear requests
// between both sides of a CDC module. It aims to solve the problem of
// initiating a CDC clear, reset one-sidedly without running into
// reset-domain-crossing issues and breaking CDC protocol assumption.
//
// Problem Formulation:
//
// CDC implementations usually face the issue that one side of the CDC must not
// be cleared without clearing the other side. E.g. clearing the write-pointer
// without clearing the read-pointer in a gray-counting CDC FIFO results in an
// invalid fill-state an may cause spurious transactions of invalid data to be
// propagated accross the CDC. A similar effect is caused in 2-phase CDC
// implementations.
//
// A naive mitigation technique would be to reset both domains asynchronously
// with the same reset signal. This will cause intra-clock domain RDC issues
// since the asynchronous clear event (assertion of the reset signal) might
// happen close to the active edge of the CDC's periphery and thus might induce
// metastability. A better, but still flawed approach would be to naively
// synchronize assertion AND deassertion (the usual rst sync only synchronize
// deassertion) of the resets into the respective other domain. However, this
// might cause the classic issue of fast-to-slow clock domain crossing where the
// clear signal is not asserted long enough to be captured by the receiving
// side. The common mitigation strategy is to use a feedback acknowledge signal
// to handshake the reset request into the other domain. One even more peculiar
// corner case this approach might suffer is the scenario where the synchronized
// clear signal arrives at the other side of the CDC within or even worse after
// the same clock cylce that the other domain crossing signals (e.g. read/write
// pointers) are cleared. In this scenario, multiple signals change within the
// same clock cycle and due to metastability we cannot be sure, that the other
// side of the CDC sees the reset assertion before the first bits of e.g. the
// write/read pointer start to switch to their reset state. Care must also be
// taken to handle the corner cases where both sides are reset simultaneously or
// the case where one side leaves reset earlier than the other.
//
// How this Module Works
//
// This module has two interfaces, the 'a' side and the 'b' side. Each side can
// be triggered using the a/b_clear_i signal or (optionally) by the asynchronous
// a/b_rst_ni. Once e.g. 'a' is triggered it will initiate a clear sequence that
// first asserts an 'a_isolate_o' signal, waits until the external circuitry
// acknowledges isolation using the 'a_isolate_ack_i'. Then the module asserts
// the 'a_clear_o' signals before some cycles later, the isolate signal is
// deasserted. This sequence ensures that no transactions can arrive to the CDC
// while the state is cleared. Now the important part is, that those four phases
// (asser isolate, assert clear, deassert clear, deassert isolate) are mirrored
// on the other side ('b') in lock-step. The cc_cdc_reset_ctrlr module uses a
// dedicated 4-phase handshaking CDC to transmit the current phase of the clear
// sequence to the other domain. We use a 4-phase rather than a 2-phase CDC to
// avoid the issues of one-sided async reset that might trigger spurious
// transactions. Furthermore, the 4-phase CDC within this module is operated in
// a special mode: Decoupled=0 ensures that there are no in-flight transactions.
// The src side only consumes the item once the destination side acknowledged
// the receiption. This property is required to transition through the phases in
// lock-step. Furthermore, (SendResetMsg=1) will cause the src side of the
// 4-phase CDC to immediately initiate the isolation phase in the dst domain
// upon asynchronous reset regardless how long the async reset stays asserted or
// whether the source clock is gated. Both sides of this module independently
// generate the sequence signals as an initiator (triggered by the clear_i or
// rst_ni signal) or receiver (trigerred for the other side). The or-ed version
// of initiator and receiver are used to generate the actual a/b_isolate_o and
// a/b_clear_o signal. That way, it doesn't matter wheter both sides
// simulatenously trigger a clear sequence, proper sequencing is still
// guaranteed.
//
// The time it takes to complete an entire clear sequence can be bounded as follows:
//
// t_clear <= 20*T+16*SyncStages*T, with T=max(T_a, T_b) (clock periods of src and dst)
//
// How to Use the Module
//
// Instantiate the module within your CDC and connect a/b_clk_i, the
// asyncrhonous a/b_rst_ni and the synchronous a/b_clear_i signals. The 'a' and
// 'b' port are entirely symetric so it doesn't matter whether you connect src
// to 'a' or 'b'. If you enable support for async reset
// (ClearOnAsyncReset==1), parametrize the number of synchronization stages
// (for metastability resolution) to be strictly less than the latency of the
// CDC. E.g. if your CDC uses 3 (the minimum) sync stages, parametrize this
// module with SyncStages < 2! Your CDC must implement a src/dst_clear_i port
// that SYNCHRONOUSLY clears all FFs on the respective side. Connect the CDC's
// src/dst_clear ports to this module's a/b_clear_o port. Once the a/b_isolate_o
// signal is asserted, the respective CDC side (src/dst) must be isolated from
// the outside world (i.e. must no longer accept any transaction on the src side
// and cease presenting or even withdrawing data on the dst side). Once your CDC
// side is isolated (depending on protocol this might take several cycles),
// assert the a/b_isolate_ack_i signal.
//
`include "common_cells/registers.svh"

module cc_cdc_reset_ctrlr
  import cc_pkg::*;
 #(
  /// The number of synchronization stages to use for the
  /// clear signal request/acknowledge. Must be less than the
  /// number of sync stages used in the CDC.
  parameter int unsigned SyncStages = 2,
  /// Whether an asynchronous reset shall cause a clear
  /// request to be sent to the other side.
  parameter logic        ClearOnAsyncReset = 1'b1
)(
  // Side A (both sides are symmetric)
  input logic  a_clk_i,
  input logic  a_rst_ni,
  input logic  a_clear_i,
  output logic a_clear_o,
  input logic a_clear_ack_i,
  output logic a_isolate_o,
  input logic  a_isolate_ack_i,
  // Side B (both sides are symmetric)
  input logic  b_clk_i,
  input logic  b_rst_ni,
  input logic  b_clear_i,
  output logic b_clear_o,
  input logic  b_clear_ack_i,
  output logic b_isolate_o,
  input logic  b_isolate_ack_i
);

  (* dont_touch = "true" *)
  logic        async_a2b_req, async_b2a_ack;
  (* dont_touch = "true" *)
  cdc_clear_seq_phase_e async_a2b_next_phase;
  (* dont_touch = "true" *)
  logic        async_b2a_req, async_a2b_ack;
  (* dont_touch = "true" *)
  cdc_clear_seq_phase_e async_b2a_next_phase;

  cc_cdc_reset_ctrlr_half #(
    .SyncStages        ( SyncStages        ),
    .ClearOnAsyncReset ( ClearOnAsyncReset )
  ) i_cdc_reset_ctrlr_half_a (
    .clk_i              ( a_clk_i              ),
    .rst_ni             ( a_rst_ni             ),
    .clear_i            ( a_clear_i            ),
    .clear_o            ( a_clear_o            ),
    .clear_ack_i        ( a_clear_ack_i        ),
    .isolate_o          ( a_isolate_o          ),
    .isolate_ack_i      ( a_isolate_ack_i      ),
    (* async *) .async_next_phase_o ( async_a2b_next_phase ),
    (* async *) .async_req_o        ( async_a2b_req        ),
    (* async *) .async_ack_i        ( async_b2a_ack        ),
    (* async *) .async_next_phase_i ( async_b2a_next_phase ),
    (* async *) .async_req_i        ( async_b2a_req        ),
    (* async *) .async_ack_o        ( async_a2b_ack        )
  );

    cc_cdc_reset_ctrlr_half #(
    .SyncStages        ( SyncStages        ),
    .ClearOnAsyncReset ( ClearOnAsyncReset )
  ) i_cdc_reset_ctrlr_half_b (
    .clk_i              ( b_clk_i              ),
    .rst_ni             ( b_rst_ni             ),
    .clear_i            ( b_clear_i            ),
    .clear_o            ( b_clear_o            ),
    .clear_ack_i        ( b_clear_ack_i        ),
    .isolate_o          ( b_isolate_o          ),
    .isolate_ack_i      ( b_isolate_ack_i      ),
    (* async *) .async_next_phase_o ( async_b2a_next_phase ),
    (* async *) .async_req_o        ( async_b2a_req        ),
    (* async *) .async_ack_i        ( async_a2b_ack        ),
    (* async *) .async_next_phase_i ( async_a2b_next_phase ),
    (* async *) .async_req_i        ( async_a2b_req        ),
    (* async *) .async_ack_o        ( async_b2a_ack        )
  );
endmodule


module cc_cdc_reset_ctrlr_half
  import cc_pkg::*;
#(
  /// The number of synchronization stages to use for the
  /// clear signal request/acknowledge. Must be less than
  /// the number of sync stages used in the CDC
  parameter int unsigned SyncStages = 2,
  /// Whether an asynchronous reset shall cause a clear
  /// request to be sent to the other side.
  parameter logic        ClearOnAsyncReset = 1'b1
)(
  // Synchronous side
  input logic                  clk_i,
  input logic                  rst_ni,
  input logic                  clear_i,
  output logic                 isolate_o,
  input logic                  isolate_ack_i,
  output logic                 clear_o,
  input logic                  clear_ack_i,
  // Asynchronous clear sequence hanshaking
  output cdc_clear_seq_phase_e async_next_phase_o,
  output logic                 async_req_o,
  input logic                  async_ack_i,
  input cdc_clear_seq_phase_e  async_next_phase_i,
  input logic                  async_req_i,
  output logic                 async_ack_o
);


  // How this module works:

  // The module is split into two parts. The initiator part consists of an FSM
  // that is triggered by the clear_i signal and transitions through reset
  // sequence. During those transitions, the `initiator_isolate_out` and
  // `initiator_clear_out` signals are asserted appropriately.

  // The receiver part receives the state transitions from the other clock
  // domain (initiator part of the `cc_cdc_reset_ctrlr_half` instance in the other
  // clock domain) and asserts the `receiver_isolate_out` and
  // `receiver_clear_out` appropriately (considering the `isolate_ack_i`
  // signal).

  // In both, the initiator and the receiver part, the respective FSM
  // transitions through 4 phases. In the ISOLATE phase, the isolate signal is
  // asserted and the connected CDCs are expected to block all further
  // interactions with the outside world and acknowledge the isolation with the
  // isolate_ack_i signal. In the CLEAR phase, the clear signal is asserted
  // which resets the internal state of the CDC while keeping the isolate signal
  // asserted. In the POST_CLEAR phase, the clear signal is deasserted. Finally,
  // when returning to the IDLE phase, the isolate signal is deasserted to
  // continue normal operation. The FSM uses a dedicated 4-phase handshaking CDC
  // to transition between the phases in lock-step and transmits the current
  // state to the other domain to avoid issues if the other domain is reset
  // asynchronously while a clear procedure is pending.

  //---------------------- Initiator Side ----------------------
  // Sends clear sequence state transitions to the other side.
   typedef enum logic[3:0] {
     IDLE,
     ISOLATE,
     WAIT_ISOLATE_PHASE_ACK,
     WAIT_ISOLATE_ACK,
     CLEAR,
     WAIT_CLEAR_PHASE_ACK,
     WAIT_CLEAR_ACK,
     POST_CLEAR,
     FINISHED
  } initiator_state_e;
  initiator_state_e initiator_state_d, initiator_state_q;
  localparam initiator_state_e InitiatorStateResetValue = ClearOnAsyncReset ? ISOLATE : IDLE;

  // The current phase of the clear sequence, sent to the other side using a
  // 4-phase CDC
  cdc_clear_seq_phase_e      initiator_clear_seq_phase;
  logic                      initiator_phase_transition_req;
  logic                      initiator_phase_transition_ack;
  logic                      initiator_isolate_out;
  logic                      initiator_clear_out;

  // The phase CDC is a real CDC even when callers pass a reduced latency for
  // synchronous-clear-only configurations.
  localparam int unsigned ResetSyncStages = (SyncStages > 2) ? SyncStages : 2;

  always_comb begin
    initiator_state_d              = initiator_state_q;
    initiator_phase_transition_req = 1'b0;
    initiator_isolate_out          = 1'b0;
    initiator_clear_out            = 1'b0;
    initiator_clear_seq_phase      = CDC_CLEAR_PHASE_IDLE;

    case (initiator_state_q)
      IDLE: begin
        if (clear_i) begin
          initiator_state_d = ISOLATE;
        end
      end

      ISOLATE: begin
        initiator_phase_transition_req = 1'b1;
        initiator_clear_seq_phase      = CDC_CLEAR_PHASE_ISOLATE;
        initiator_isolate_out          = 1'b1;
        initiator_clear_out            = 1'b0;
        if (initiator_phase_transition_ack && isolate_ack_i) begin
          initiator_state_d = CLEAR;
        end else if (initiator_phase_transition_ack) begin
          initiator_state_d = WAIT_ISOLATE_ACK;
        end else if (isolate_ack_i) begin
          initiator_state_d = WAIT_ISOLATE_PHASE_ACK;
        end
      end

      WAIT_ISOLATE_ACK: begin
        initiator_isolate_out     = 1'b1;
        initiator_clear_out       = 1'b0;
        initiator_clear_seq_phase = CDC_CLEAR_PHASE_ISOLATE;
        if (isolate_ack_i) begin
          initiator_state_d = CLEAR;
        end
      end

      WAIT_ISOLATE_PHASE_ACK: begin
        initiator_phase_transition_req = 1'b1;
        initiator_clear_seq_phase      = CDC_CLEAR_PHASE_ISOLATE;
        initiator_isolate_out          = 1'b1;
        initiator_clear_out            = 1'b0;
        if (initiator_phase_transition_ack) begin
          initiator_state_d = CLEAR;
        end
      end

      CLEAR: begin
        initiator_isolate_out          = 1'b1;
        initiator_clear_out            = 1'b1;
        initiator_phase_transition_req = 1'b1;
        initiator_clear_seq_phase      = CDC_CLEAR_PHASE_CLEAR;
        if (initiator_phase_transition_ack && clear_ack_i) begin
          initiator_state_d = POST_CLEAR;
        end else if (initiator_phase_transition_ack) begin
          initiator_state_d = WAIT_CLEAR_ACK;
        end else if (clear_ack_i) begin
          initiator_state_d = WAIT_CLEAR_PHASE_ACK;
        end
      end

      WAIT_CLEAR_ACK: begin
        initiator_isolate_out     = 1'b1;
        initiator_clear_out       = 1'b1;
        initiator_clear_seq_phase = CDC_CLEAR_PHASE_CLEAR;
        if (clear_ack_i) begin
          initiator_state_d = POST_CLEAR;
        end
      end

      WAIT_CLEAR_PHASE_ACK: begin
        initiator_phase_transition_req = 1'b1;
        initiator_clear_seq_phase      = CDC_CLEAR_PHASE_CLEAR;
        initiator_isolate_out          = 1'b1;
        initiator_clear_out            = 1'b1;
        if (initiator_phase_transition_ack) begin
          initiator_state_d = POST_CLEAR;
        end
      end

      POST_CLEAR: begin
        initiator_isolate_out          = 1'b1;
        initiator_clear_out            = 1'b0;
        initiator_phase_transition_req = 1'b1;
        initiator_clear_seq_phase      = CDC_CLEAR_PHASE_POST_CLEAR;
        if (initiator_phase_transition_ack) begin
          initiator_state_d = FINISHED;
        end
      end

      FINISHED: begin
        initiator_isolate_out          = 1'b1;
        initiator_clear_out            = 1'b0;
        initiator_phase_transition_req = 1'b1;
        initiator_clear_seq_phase      = CDC_CLEAR_PHASE_IDLE;
        if (initiator_phase_transition_ack) begin
          initiator_state_d = IDLE;
        end
      end

      default: begin
        initiator_state_d = ISOLATE;
      end
    endcase
  end

  // Start in the ISOLATE state if asynchronous reset should launch a clear sequence.
  `FF(initiator_state_q, initiator_state_d, InitiatorStateResetValue, clk_i, rst_ni)

  // Initiator CDC SRC
  // We use 4 phase handshaking. That way it doesn't matter if one side is
  // sudenly reset asynchronously. With a 2phase CDC, one-sided async resets might
  // introduce spurios transactions.

  cc_cdc_4phase_src #(
    .data_t(cdc_clear_seq_phase_e),
    .SyncStages(ResetSyncStages),
    .Decoupled(0), // Important! The CDC must not be in decoupled mode.
                   // Otherwise we will proceed to the next state without
                   // waiting for the new state to arrive on the other side.
    .SendResetMsg(ClearOnAsyncReset), // Send the ISOLATE phase request immediately on async
                                      // reset if async reset synchronization is enabled.
    .ResetMsg(CDC_CLEAR_PHASE_ISOLATE)
  ) i_state_transition_cdc_src(
    .clk_i,
    .rst_ni,
    .data_i(initiator_clear_seq_phase),
    .valid_i(initiator_phase_transition_req),
    .ready_o(initiator_phase_transition_ack),
    .async_req_o,
    .async_ack_i,
    .async_data_o(async_next_phase_o)
  );


  //---------------------- Receiver Side ----------------------
  // This part of the circuit receives clear sequence state transitions from the
  // other side.

  cdc_clear_seq_phase_e receiver_phase_d, receiver_phase_q;
  cdc_clear_seq_phase_e receiver_effective_phase;
  cdc_clear_seq_phase_e receiver_next_phase;

  logic receiver_phase_req;
  logic receiver_phase_ack;
  logic receiver_phase_pending_d, receiver_phase_pending_q;
  logic receiver_phase_done_d, receiver_phase_done_q;

  logic receiver_capture_phase;

  logic receiver_isolate_out;
  logic receiver_clear_out;

  cc_cdc_4phase_dst #(
    .data_t(cdc_clear_seq_phase_e),
    .SyncStages(ResetSyncStages),
    .Decoupled(0) // Important! The CDC must not be in decoupled mode. Otherwise
                  // we will proceed to the next state without waiting for the
                  // new state to arrive on the other side.
  ) i_state_transition_cdc_dst(
    .clk_i,
    .rst_ni,
    .data_o(receiver_next_phase),
    .valid_o(receiver_phase_req),
    .ready_i(receiver_phase_ack),
    .async_req_i,
    .async_ack_o,
    .async_data_i(async_next_phase_i)
  );

  // Capture async phase payload after synchronized request
  // Do not decode receiver_next_phase into clear/isolate
  assign receiver_capture_phase =
      receiver_phase_req
   && !receiver_phase_pending_q
   && !receiver_phase_done_q;

  always_comb begin
    receiver_phase_d         = receiver_phase_q;
    receiver_phase_pending_d = receiver_phase_pending_q;
    receiver_phase_done_d    = receiver_phase_done_q;

    if (!receiver_phase_req) begin
      receiver_phase_done_d = 1'b0;
    end

    if (receiver_capture_phase) begin
      receiver_phase_d         = receiver_next_phase;
      receiver_phase_pending_d = 1'b1;
    end

    if (receiver_phase_ack) begin
      receiver_phase_pending_d = 1'b0;
      receiver_phase_done_d    = 1'b1;
    end
  end

  `FF(receiver_phase_q,         receiver_phase_d,         CDC_CLEAR_PHASE_IDLE, clk_i, rst_ni)
  `FF(receiver_phase_pending_q, receiver_phase_pending_d, 1'b0,                 clk_i, rst_ni)
  `FF(receiver_phase_done_q,    receiver_phase_done_d,    1'b0,                 clk_i, rst_ni)

  assign receiver_effective_phase = receiver_phase_q;

  always_comb begin
    receiver_isolate_out = 1'b0;
    receiver_clear_out   = 1'b0;
    receiver_phase_ack   = 1'b0;

    unique case (receiver_effective_phase)
      CDC_CLEAR_PHASE_IDLE: begin
        receiver_clear_out   = 1'b0;
        receiver_isolate_out = 1'b0;
        receiver_phase_ack   = receiver_phase_req && receiver_phase_pending_q;
      end
      CDC_CLEAR_PHASE_ISOLATE: begin
        receiver_clear_out   = 1'b0;
        receiver_isolate_out = 1'b1;
        receiver_phase_ack   = receiver_phase_req && receiver_phase_pending_q && isolate_ack_i;
      end
      CDC_CLEAR_PHASE_CLEAR: begin
        receiver_clear_out   = 1'b1;
        receiver_isolate_out = 1'b1;
        receiver_phase_ack   = receiver_phase_req && receiver_phase_pending_q && clear_ack_i;
      end
      CDC_CLEAR_PHASE_POST_CLEAR: begin
        receiver_clear_out   = 1'b0;
        receiver_isolate_out = 1'b1;
        receiver_phase_ack   = receiver_phase_req && receiver_phase_pending_q;
      end
      default: begin
        receiver_clear_out   = 1'b0;
        receiver_isolate_out = 1'b0;
        receiver_phase_ack   = 1'b0;
      end
    endcase

    // Preserve async-reset ordering margin without async_next_phase_i decode
    if (receiver_capture_phase) begin
      receiver_isolate_out = 1'b1;
    end
  end

  // Output Assignment

  // The clear and isolate signal are the OR combination of the receiver and
  // initiator's clear/isolate signal. This ensures that the correct sequence is
  // followed even if both sides are cleared independently at roughly the same
  // time.
  assign clear_o = initiator_clear_out || receiver_clear_out;
  assign isolate_o = initiator_isolate_out || receiver_isolate_out;

endmodule : cc_cdc_reset_ctrlr_half