[PATCH net-next v11 10/13] dpll: sit9531x: implement output pin state on a DPLL

[Ali Rouhi <arouhi@sitime.com>]

From: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>

An output is driven by its PLL rather than selected by it, so its state
says whether it carries a signal: connected while it drives, disconnected
while it is muted.  Setting the state mutes or un-mutes it by forcing the
pad to Hi-Z, the only per-output control the device offers that leaves the
divider alone.

The force bit and the state bit are separate, and a pad follows the loaded
configuration while the force bit is clear, so both are read to decide
whether an output is muted and both are written to change it.  Which of
the four register banks applies depends on the slot and on whether the pad
is single-ended or differential.

This is also where output pins start being registered at all: until now
the registration filter took inputs only, so the output operations the
earlier patches added -- direction and frequency -- had nothing to
dispatch on.

Signed-off-by: Oleg Zadorozhnyi <Oleg.Zadorozhnyi@devoxsoftware.com>
Assisted-by: Claude:claude-4-opus [chat]
Signed-off-by: Ali Rouhi <arouhi@sitime.com>
---
 drivers/dpll/sit9531x/core.c | 271 ++++++++++++++++++++++++++++++++++-
 drivers/dpll/sit9531x/core.h |   7 +
 drivers/dpll/sit9531x/dpll.c | 102 +++++++++++++
 3 files changed, 374 insertions(+), 6 deletions(-)

diff --git a/drivers/dpll/sit9531x/core.c b/drivers/dpll/sit9531x/core.c
index 3254d119b939..8fed14d8dca6 100644
--- a/drivers/dpll/sit9531x/core.c
+++ b/drivers/dpll/sit9531x/core.c
@@ -488,6 +488,47 @@ static int sit9531x_output_forced_hiz(struct sit9531x_dev *sitdev,
 					muted);
 }
 
+/*
+ * sit9531x_output_state_refresh - read an output's mute state back
+ *
+ * Used when a mute could not be confirmed at the time it was written.  The
+ * driver does not poll output state, so without this the cached value would
+ * stand until something else happened to write it.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_output_state_refresh(struct sit9531x_dev *sitdev, u8 out_idx)
+{
+	bool muted;
+	int rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	rc = sit9531x_output_forced_hiz(sitdev, out_idx, &muted);
+	if (rc)
+		return rc;
+
+	sitdev->out[out_idx].enabled = !muted;
+	sitdev->out[out_idx].state_stale = false;
+
+	return 0;
+}
+
+static int sit9531x_hiz_set_bit(struct sit9531x_dev *sitdev,
+				unsigned int reg, u8 bit, bool set)
+{
+	u8 cur, new_val;
+	int rc;
+
+	rc = sit9531x_read_u8(sitdev, reg, &cur);
+	if (rc)
+		return rc;
+
+	new_val = set ? (cur | BIT(bit)) : (cur & ~BIT(bit));
+
+	return sit9531x_write_u8(sitdev, reg, new_val);
+}
+
 /* Attempts to re-lock the output loops before reporting them open. */
 #define SIT9531X_LOOP_LOCK_TRIES	3
 
@@ -621,6 +662,212 @@ static int sit9531x_prg_commit(struct sit9531x_dev *sitdev)
 	return 0;
 }
 
+/*
+ * sit9531x_output_hiz_write - mute or unmute an output
+ *
+ * Muting takes control of the pin (MASK=1) and forces it to Hi-Z
+ * (STATE=0) on every Hi-Z pair of the slot -- differential, CMOS OutP
+ * and CMOS OutN -- because the output must go quiet whichever way it is
+ * wired; unmuting releases the override on all of them and hands the pin
+ * back to the device.  The caller must already be in the programming
+ * state.
+ */
+static int sit9531x_output_hiz_write(struct sit9531x_dev *sitdev, u8 slot,
+				     bool mute)
+{
+	struct sit9531x_hiz_pair p[SIT9531X_HIZ_PAIRS];
+	u8 mask[SIT9531X_HIZ_PAIRS], state[SIT9531X_HIZ_PAIRS];
+	int i, rc, undo_rc;
+
+	sit9531x_output_get_hiz_regs(slot, p);
+
+	if (!mute) {
+		for (i = 0; i < SIT9531X_HIZ_PAIRS; i++) {
+			rc = sit9531x_hiz_set_bit(sitdev, p[i].mask, p[i].bit,
+						  false);
+			if (rc)
+				return rc;
+		}
+		return 0;
+	}
+
+	/*
+	 * Remember every pair as it was: if the mute fails part-way, that
+	 * is what the pad goes back to -- which may already be a mute, from
+	 * an earlier request or from the loaded profile.
+	 */
+	for (i = 0; i < SIT9531X_HIZ_PAIRS; i++) {
+		rc = sit9531x_read_u8(sitdev, p[i].state, &state[i]);
+		if (rc)
+			return rc;
+		rc = sit9531x_read_u8(sitdev, p[i].mask, &mask[i]);
+		if (rc)
+			return rc;
+	}
+
+	/*
+	 * Forced value first, override enable second.  Muted is decoded as
+	 * MASK set with STATE clear, so enabling the override while STATE
+	 * still holds whatever the loaded configuration left there can pin
+	 * the pad driven for the width of an I2C transfer.
+	 */
+	for (i = 0; i < SIT9531X_HIZ_PAIRS; i++) {
+		rc = sit9531x_hiz_set_bit(sitdev, p[i].state, p[i].bit, false);
+		if (!rc)
+			rc = sit9531x_hiz_set_bit(sitdev, p[i].mask, p[i].bit,
+						  true);
+		if (rc)
+			break;
+	}
+	if (!rc)
+		return 0;
+
+	/*
+	 * Only part of the mute reached the device.  Put every pair it may
+	 * have touched back to the bits read above -- override first, then
+	 * value, the reverse of the order they went on -- so the pad ends
+	 * where the request started rather than on part of a mute, or
+	 * un-muted when it was muted before.
+	 */
+	for (; i >= 0; i--) {
+		undo_rc = sit9531x_hiz_set_bit(sitdev, p[i].mask, p[i].bit,
+					       mask[i] & BIT(p[i].bit));
+		if (!undo_rc)
+			undo_rc = sit9531x_hiz_set_bit(sitdev, p[i].state,
+						       p[i].bit,
+						       state[i] & BIT(p[i].bit));
+		if (undo_rc)
+			dev_err(sitdev->dev,
+				"slot%u: Hi-Z override left part applied (%d)\n",
+				slot, undo_rc);
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_output_disable - mute an output (force Hi-Z)
+ * @index:	logical output index (0..info->num_outputs-1)
+ *
+ * Sets MASK and clears STATE on every Hi-Z pair of the slot, differential
+ * and both CMOS pads, so that the output is muted regardless of its
+ * electrical configuration.  The
+ * writes are wrapped in the PRG_CMD / NVM update / loop lock sequence
+ * so the new state is applied by the hardware.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_output_disable(struct sit9531x_dev *sitdev, u8 index)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	bool muted;
+	u8 slot;
+	int rc, ret, state_rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (index >= info->num_outputs)
+		return -EINVAL;
+
+	slot = info->clkout_map[index];
+	rc = sit9531x_prg_enter(sitdev);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_hiz_write(sitdev, slot, true);
+
+	/*
+	 * Always leave the PRG_CMD programming state, even on a mid-sequence
+	 * write failure: prg_enter() unlocked the output loops, so returning
+	 * without prg_commit() would strand the chip in the programming state
+	 * with the loops unlocked.  Best effort -- keep the first error.
+	 */
+	ret = sit9531x_prg_commit(sitdev);
+	if (ret && !rc)
+		rc = ret;
+
+	/*
+	 * Keep the software state aligned to what hardware now drives even
+	 * when one write in the sequence failed. The commit above may have
+	 * applied a partial mask/state combination.
+	 */
+	state_rc = sit9531x_output_forced_hiz(sitdev, index, &muted);
+	if (!state_rc) {
+		sitdev->out[index].enabled = !muted;
+		sitdev->out[index].state_stale = false;
+	} else {
+		/*
+		 * The writes may well have landed; what failed is the proof.
+		 * Mark the cached state for a read-through rather than
+		 * reporting the value it had before this call.
+		 */
+		sitdev->out[index].state_stale = true;
+		if (!rc)
+			rc = state_rc;
+	}
+
+	return rc;
+}
+
+/*
+ * sit9531x_output_enable - un-mute an output (active state)
+ * @index:	logical output index (0..info->num_outputs-1)
+ *
+ * Releases MASK on every Hi-Z pair so the device drives the output
+ * again as the loaded profile configures it.  The writes are wrapped
+ * in the PRG_CMD / NVM update / loop lock sequence so the new state is
+ * applied by the hardware.
+ *
+ * Caller must hold sitdev->multiop_lock.
+ */
+int sit9531x_output_enable(struct sit9531x_dev *sitdev, u8 index)
+{
+	const struct sit9531x_chip_info *info = sitdev->info;
+	bool muted;
+	u8 slot;
+	int rc, ret, state_rc;
+
+	lockdep_assert_held(&sitdev->multiop_lock);
+
+	if (index >= info->num_outputs)
+		return -EINVAL;
+
+	slot = info->clkout_map[index];
+	rc = sit9531x_prg_enter(sitdev);
+	if (rc)
+		return rc;
+
+	rc = sit9531x_output_hiz_write(sitdev, slot, false);
+
+	/*
+	 * Always leave the PRG_CMD programming state, even on a mid-sequence
+	 * write failure: prg_enter() unlocked the output loops, so returning
+	 * without prg_commit() would strand the chip in the programming state
+	 * with the loops unlocked.  Best effort -- keep the first error.
+	 */
+	ret = sit9531x_prg_commit(sitdev);
+	if (ret && !rc)
+		rc = ret;
+
+	/* See sit9531x_output_disable(): commit can apply part of it. */
+	state_rc = sit9531x_output_forced_hiz(sitdev, index, &muted);
+	if (!state_rc) {
+		sitdev->out[index].enabled = !muted;
+		sitdev->out[index].state_stale = false;
+	} else {
+		/*
+		 * The writes may well have landed; what failed is the proof.
+		 * Mark the cached state for a read-through rather than
+		 * reporting the value it had before this call.
+		 */
+		sitdev->out[index].state_stale = true;
+		if (!rc)
+			rc = state_rc;
+	}
+
+	return rc;
+}
+
 /*
  * Input priority selection
  *
@@ -2348,6 +2595,8 @@ static int sit9531x_out_state_fetch(struct sit9531x_dev *sitdev, u8 index)
 	if (rc)
 		return rc;
 
+	sitdev->out[index].state_stale = false;
+
 	/*
 	 * Each PLL page holds the PLL's output-enable mask, twelve bits:
 	 * bits 0-7 in OUT_MAP_LO and bits 8-11 in OUT_MAP_HI[3:0].  PLLA and
@@ -3165,8 +3414,8 @@ static void sit9531x_dpll_pins_unregister(struct sit9531x_dpll *sitdpll)
  * @index:	pin hardware index
  *
  * For input pins: delegate to sit9531x_input_pin_is_registrable().
- * A pin class whose state callback the tree does not have yet is not
- * registrable: the core refuses a pin without one.
+ * For output pins: the pin is registrable if this DPLL is routed to it,
+ * whether or not it is currently driving.
  *
  * Return: true if pin should be registered, false otherwise
  */
@@ -3176,13 +3425,23 @@ static bool sit9531x_dpll_pin_is_registrable(struct sit9531x_dpll *sitdpll,
 {
 	struct sit9531x_dev *sitdev = sitdpll->dev;
 
-	if (dir != DPLL_PIN_DIRECTION_INPUT)
+	if (dir == DPLL_PIN_DIRECTION_INPUT) {
+		if (index == SIT9531X_MAX_INPUTS)
+			return true;
+		if (index == SIT9531X_INTSYNC_PIN_ID)
+			return false;
+
+		return sit9531x_input_pin_is_registrable(sitdev, index);
+	}
+
+	if (index == SIT9531X_INTSYNC_OUT_PIN_ID)
 		return false;
 
-	if (index == SIT9531X_MAX_INPUTS)
-		return true;
+	if (index >= sitdev->info->num_outputs)
+		return false;
 
-	return sit9531x_input_pin_is_registrable(sitdev, index);
+	return sitdev->out[index].pll_idx == sitdpll->id &&
+	       sitdev->out[index].routed;
 }
 
 /*
diff --git a/drivers/dpll/sit9531x/core.h b/drivers/dpll/sit9531x/core.h
index 473171a19d94..8e1378d04b77 100644
--- a/drivers/dpll/sit9531x/core.h
+++ b/drivers/dpll/sit9531x/core.h
@@ -99,6 +99,8 @@ struct sit9531x_ref {
  * @cmos:		output is wired single-ended; the Hi-Z pairs that
  *			speak for it are the two CMOS pad ones, not the
  *			differential
+ * @state_stale:	the cached mute state could not be confirmed against
+ *			hardware and has to be read back before it is reported
  * @routed:		output is mapped to @pll_idx by the initial
  *			configuration; an unrouted output has no DPLL pin
  * @pll_idx:		PLL driving this output (0-3)
@@ -107,6 +109,7 @@ struct sit9531x_out {
 	u64		freq;
 	bool		enabled;
 	bool		cmos;
+	bool		state_stale;
 	bool		routed;
 	u8		pll_idx;
 };
@@ -258,6 +261,10 @@ int sit9531x_input_prio_add(struct sit9531x_dev *sitdev, u8 pll_idx,
 			    u8 input_idx);
 
 /* ---- Output enable/disable (Hi-Z control) ---- */
+int sit9531x_output_disable(struct sit9531x_dev *sitdev, u8 index);
+int sit9531x_output_enable(struct sit9531x_dev *sitdev, u8 index);
+int sit9531x_output_state_refresh(struct sit9531x_dev *sitdev,
+				  u8 out_idx);
 
 /* ---- Output frequency ---- */
 int sit9531x_output_freq_set(struct sit9531x_dev *sitdev, u8 out_idx,
diff --git a/drivers/dpll/sit9531x/dpll.c b/drivers/dpll/sit9531x/dpll.c
index a576d918e68d..ac2d977d36f7 100644
--- a/drivers/dpll/sit9531x/dpll.c
+++ b/drivers/dpll/sit9531x/dpll.c
@@ -751,10 +751,112 @@ sit9531x_dpll_output_pin_frequency_set(const struct dpll_pin *pin,
 	return rc;
 }
 
+/*
+ * sit9531x_dpll_output_pin_state_on_dpll_get - get output pin state
+ *
+ * reports CONNECTED when the output is driven and
+ * DISCONNECTED when it has been muted via sit9531x_output_disable().
+ */
+static int
+sit9531x_dpll_output_pin_state_on_dpll_get(const struct dpll_pin *pin,
+					   void *pin_priv,
+					   const struct dpll_device *dpll,
+					   void *dpll_priv,
+					   enum dpll_pin_state *state,
+					   struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	const struct sit9531x_out *out;
+	int rc;
+
+	/*
+	 * A mute whose read-back failed left the cache unconfirmed; there is
+	 * no poll of output state to correct it, so read it here rather than
+	 * report a value that may predate the request.
+	 */
+	if (sitdev->out[dpin->id].state_stale) {
+		mutex_lock(&sitdev->multiop_lock);
+		rc = sit9531x_output_state_refresh(sitdev, dpin->id);
+		mutex_unlock(&sitdev->multiop_lock);
+		if (rc) {
+			NL_SET_ERR_MSG(extack,
+				       "Output mute state could not be read back");
+			return rc;
+		}
+	}
+
+	out = sit9531x_out_state_get(sitdev, dpin->id);
+	*state = out->enabled ? DPLL_PIN_STATE_CONNECTED
+			      : DPLL_PIN_STATE_DISCONNECTED;
+	return 0;
+}
+
+/*
+ * sit9531x_dpll_output_pin_state_on_dpll_set - mute/un-mute an output
+ *
+ * Forces Hi-Z on the output through the Hi-Z force/state register pairs
+ * of its slot, the differential and the single-ended one.
+ *   CONNECTED    -> enable (release the override, the device drives it)
+ *   DISCONNECTED -> disable (force Hi-Z)
+ */
+static int
+sit9531x_dpll_output_pin_state_on_dpll_set(const struct dpll_pin *pin,
+					   void *pin_priv,
+					   const struct dpll_device *dpll,
+					   void *dpll_priv,
+					   enum dpll_pin_state state,
+					   struct netlink_ext_ack *extack)
+{
+	struct sit9531x_dpll_pin *dpin = pin_priv;
+	struct sit9531x_dpll *sitdpll = dpll_priv;
+	struct sit9531x_dev *sitdev = sitdpll->dev;
+	bool was_enabled, changed;
+	int rc;
+
+	mutex_lock(&sitdev->multiop_lock);
+
+	was_enabled = sitdev->out[dpin->id].enabled;
+
+	switch (state) {
+	case DPLL_PIN_STATE_CONNECTED:
+		rc = sit9531x_output_enable(sitdev, dpin->id);
+		break;
+	case DPLL_PIN_STATE_DISCONNECTED:
+		rc = sit9531x_output_disable(sitdev, dpin->id);
+		break;
+	default:
+		rc = -EINVAL;
+		break;
+	}
+
+	changed = sitdev->out[dpin->id].enabled != was_enabled;
+
+	mutex_unlock(&sitdev->multiop_lock);
+
+	if (rc) {
+		NL_SET_ERR_MSG(extack, "Failed to set output pin state");
+		/*
+		 * The core notifies only a request that succeeded, and the
+		 * poll does not watch outputs.  A failed request whose
+		 * read-back shows the output did change still has to be
+		 * announced, or subscribers keep the old state for good.
+		 * The core's lock is held here, as the helper requires.
+		 */
+		if (changed)
+			__dpll_pin_change_ntf(dpin->dpll_pin);
+	}
+
+	return rc;
+}
+
 static const struct dpll_pin_ops sit9531x_dpll_output_pin_ops = {
 	.direction_get		= sit9531x_dpll_output_pin_direction_get,
 	.frequency_get		= sit9531x_dpll_output_pin_frequency_get,
 	.frequency_set		= sit9531x_dpll_output_pin_frequency_set,
+	.state_on_dpll_get	= sit9531x_dpll_output_pin_state_on_dpll_get,
+	.state_on_dpll_set	= sit9531x_dpll_output_pin_state_on_dpll_set,
 };
 
 const struct dpll_pin_ops *
-- 
2.43.0