Re: [PATCH v3 net-next 5/8] mfd: zl3073x: Add functions to work with register mailboxes

[Ivan Vecera <ivecera@redhat.com>]

On 16. 04. 25 8:27 odp., Ivan Vecera wrote:
> On Wed, Apr 16, 2025 at 7:32 PM Andrew Lunn <andrew@lunn.ch> wrote:
>>
>>> +/**
>>> + * zl3073x_mb_dpll_read - read given DPLL configuration to mailbox
>>> + * @zldev: pointer to device structure
>>> + * @index: DPLL index
>>> + *
>>> + * Reads configuration of given DPLL into DPLL mailbox.
>>> + *
>>> + * Context: Process context. Expects zldev->regmap_lock to be held by caller.
>>> + * Return: 0 on success, <0 on error
>>> + */
>>> +int zl3073x_mb_dpll_read(struct zl3073x_dev *zldev, u8 index)
>>> +{
>>> +     int rc;
>>
>> lockdep_assert_held(zldev->regmap_lock) is stronger than having a
>> comment. When talking about i2c and spi devices, it costs nothing, and
>> catches bugs early.
> 
> Makes sense to put the assert here...
> 
> Will add.
> 
>>
>>> +/*
>>> + * Mailbox operations
>>> + */
>>> +int zl3073x_mb_dpll_read(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_dpll_write(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_output_read(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_output_write(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_ref_read(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_ref_write(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_synth_read(struct zl3073x_dev *zldev, u8 index);
>>> +int zl3073x_mb_synth_write(struct zl3073x_dev *zldev, u8 index);
>>
>> I assume these are the only valid ways to access a mailbox?
>>
>> If so:
>>
>>> +static inline __maybe_unused int
>>> +zl3073x_mb_read_ref_mb_mask(struct zl3073x_dev *zldev, u16 *value)
>>> +{
>>> +     __be16 temp;
>>> +     int rc;
>>> +
>>> +     lockdep_assert_held(&zldev->mailbox_lock);
>>> +     rc = regmap_bulk_read(zldev->regmap, ZL_REG_REF_MB_MASK, &temp,
>>> +                           sizeof(temp));
>>> +     if (rc)
>>> +             return rc;
>>> +
>>> +     *value = be16_to_cpu(temp);
>>> +     return rc;
>>> +}
>>
>> These helpers can be made local to the core. You can then drop the
>> lockdep_assert_held() from here, since the only way to access them is
>> via the API you defined above, and add the checks in those API
>> functions.
> 
> This cannot be done this way... the above API just simplifies the
> operation of read and write latch registers from/to mailbox.
> 
> Whole operation is described in the commit description.
> 
> E.g. read something about DPLL1
> 1. Call zl3073x_mb_dpll_read(..., 1)
>     This selects DPLL1 in the DPLL mailbox and performs read operation
> and waits for finish
> 2. Call zl3073x_mb_read_dpll_mode()
>     This reads dpll_mode latch register
> 
> write:
> 1. Call zl3073x_mb_write_dpll_mode(...)
>     This writes mode to dpll_mode latch register
> 2. Call zl3073x_mb_dpll_read(..., 1)
>     This writes all info from latch registers to DPLL1
> 
> The point is that between step 1 and 2 nobody else cannot touch
> latch_registers or mailbox select register and op semaphore.
> 

Anyway, I have a different idea... completely abstract mailboxes from 
the caller. The mailbox content can be large and the caller is barely 
interested in all registers from the mailbox but this could be resolved 
this way:

The proposed API e.g for Ref mailbox:

int zl3073x_mb_ref_read(struct zl3073x_dev *zldev, u8 index,
                         struct zl3073x_mb_ref *mb);
int zl3073x_mb_ref_write(struct zl3073x_dev *zldev, u8 index,
                          struct zl3073x_mb_ref *mb);

struct zl3073x_mb_ref {
	u32	flags;
	u16	freq_base;
	u16	freq_mult;
	u16	ratio_m;
	u16	ratio_n;
	u8	config;
	u64	phase_offset_compensation;
	u8	sync_ctrl;
	u32	esync_div;
}

#define ZL3073X_MB_REF_FREQ_BASE			BIT(0)
#define ZL3073X_MB_REF_FREQ_MULT			BIT(1)
#define ZL3073X_MB_REF_RATIO_M				BIT(2)
#define ZL3073X_MB_REF_RATIO_N			 	BIT(3)
#define ZL3073X_MB_REF_CONFIG			 	BIT(4)
#define ZL3073X_MB_REF_PHASE_OFFSET_COMPENSATION 	BIT(5)
#define ZL3073X_MB_REF_SYNC_CTRL			BIT(6)
#define ZL3073X_MB_REF_ESYNC_DIV			BIT(7)

Then a reader can read this way (read freq and ratio of 3rd ref):
{
	struct zl3073x_mb_ref mb;
	...
	mb.flags = ZL3073X_MB_REF_FREQ_BASE |
		   ZL3073X_MB_REF_FREQ_MULT |
		   ZL3073X_MB_REF_RATIO_M |
		   ZL3073X_MB_REF_RATIO_N;
	rc = zl3073x_mb_ref_read(zldev, 3, &mb);
	if (rc)
		return rc;
	/* at this point mb fields requested via flags are filled */
}
A writer similarly (write config of 5th ref):
{
	struct zl3073x_mb_ref mb;
	...
	mb.flags = ZL3073X_MB_REF_CONFIG;
	mb.config = FIELD_PREP(SOME_MASK, SOME_VALUE);
	rc = zl3073x_mb_ref_write(zldev, 5, &mb);
	...
	/* config of 5th ref was commited */
}

The advantages:
* no explicit locking required from the callers
* locking is done inside mailbox API
* each mailbox type can have different mutex so multiple calls for
   different mailbox types (e.g ref & output) can be done in parallel

WDYT about this approach?

Thanks,
Ivan