[PATCH net-next 0/4] dpll: fix lies in the Netlink spec

[PATCH net-next 0/4] dpll: fix lies in the Netlink spec

[Jakub Kicinski]

Clashiko started accumulating pre-existing issues in specs so I did
a scan of the families. This set fixes issues discovered in dpll.

Jakub Kicinski (4):
  netlink: specs: dpll: add clock-quality-level to the device-get reply
  netlink: specs: dpll: drop the pin-set attributes nothing implements
  netlink: specs: dpll: pin-get has no dump filter
  MAINTAINERS: dpll: add the netlink spec

 MAINTAINERS                           |  1 +
 Documentation/netlink/specs/dpll.yaml | 15 ++++-----------
 drivers/dpll/dpll_nl.c                | 20 +++++---------------
 3 files changed, 10 insertions(+), 26 deletions(-)

-- 
2.55.0

[PATCH net-next 1/4] netlink: specs: dpll: add clock-quality-level to the device-get reply

[Jakub Kicinski]

dpll_device_get_one() calls dpll_msg_add_clock_quality_level(), which
puts DPLL_A_CLOCK_QUALITY_LEVEL into every device-get reply, dump entry
and device-*-ntf of a device whose driver implements
clock_quality_level_get() - mlx5 does. The &dev-attrs anchor lists 12
attributes and not this one, so struct dpll_device_get_rsp has no field
for it, dpll_device_get_rsp_parse() drops it and dpll.rst does not
document it.

The attribute itself is correctly declared in the dpll attribute set,
only the reply list was missing an entry. Missing since commit
a1afb959add1 ("dpll: add clock quality level attribute and op").

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 Documentation/netlink/specs/dpll.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml
index cdc8c7b456df..64a45088c027 100644
--- a/Documentation/netlink/specs/dpll.yaml
+++ b/Documentation/netlink/specs/dpll.yaml
@@ -632,6 +632,7 @@ doc: DPLL subsystem.
             - mode-supported
             - lock-status
             - lock-status-error
+            - clock-quality-level
             - temp
             - clock-id
             - type
-- 
2.55.0

[PATCH net-next 2/4] netlink: specs: dpll: drop the pin-set attributes nothing implements

[Jakub Kicinski]

pin-set advertises top level direction, prio and state, so the
generated policy accepts them and the generated user space API grows
setters for them. dpll_pin_set_from_nlattr() has cases only for
FREQUENCY, PHASE_ADJUST, PARENT_DEVICE, PARENT_PIN, ESYNC_FREQUENCY and
REFERENCE_SYNC - the request succeeds, does nothing and produces no
extack. The three values are only actionable inside the parent-device
nest, where dpll_pin_parent_device_set() handles them next to
DPLL_A_PIN_PARENT_ID, which is what makes them meaningful: a pin can be
registered with more than one device.

Never implemented - "git log -S 'case DPLL_A_PIN_PRIO'" on
dpll_netlink.c comes up empty - the spec has advertised them since
commit 3badff3a25d8 ("dpll: spec: Add Netlink spec in YAML").

Note that this does change what the kernel accepts: sending one of the
three now fails validation instead of being ignored.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 Documentation/netlink/specs/dpll.yaml | 3 ---
 drivers/dpll/dpll_nl.c                | 3 ---
 2 files changed, 6 deletions(-)

diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml
index 64a45088c027..93e546ba1f56 100644
--- a/Documentation/netlink/specs/dpll.yaml
+++ b/Documentation/netlink/specs/dpll.yaml
@@ -760,9 +760,6 @@ doc: DPLL subsystem.
           attributes:
             - id
             - frequency
-            - direction
-            - prio
-            - state
             - parent-device
             - parent-pin
             - phase-adjust
diff --git a/drivers/dpll/dpll_nl.c b/drivers/dpll/dpll_nl.c
index b1ba490e72b0..3bdabbf2b931 100644
--- a/drivers/dpll/dpll_nl.c
+++ b/drivers/dpll/dpll_nl.c
@@ -78,9 +78,6 @@ static const struct nla_policy dpll_pin_get_dump_nl_policy[DPLL_A_PIN_ID + 1] =
 static const struct nla_policy dpll_pin_set_nl_policy[DPLL_A_PIN_REFERENCE_SYNC + 1] = {
 	[DPLL_A_PIN_ID] = { .type = NLA_U32, },
 	[DPLL_A_PIN_FREQUENCY] = { .type = NLA_U64, },
-	[DPLL_A_PIN_DIRECTION] = NLA_POLICY_RANGE(NLA_U32, 1, 2),
-	[DPLL_A_PIN_PRIO] = { .type = NLA_U32, },
-	[DPLL_A_PIN_STATE] = NLA_POLICY_RANGE(NLA_U32, 1, 3),
 	[DPLL_A_PIN_PARENT_DEVICE] = NLA_POLICY_NESTED(dpll_pin_parent_device_nl_policy),
 	[DPLL_A_PIN_PARENT_PIN] = NLA_POLICY_NESTED(dpll_pin_parent_pin_nl_policy),
 	[DPLL_A_PIN_PHASE_ADJUST] = { .type = NLA_S32, },
-- 
2.55.0

[PATCH net-next 3/4] netlink: specs: dpll: pin-get has no dump filter

[Jakub Kicinski]

The op doc promises "dump request with target dpll - list all the pins
registered with a given dpll device" and "do request with target dpll
and target pin". Neither exists. pin-get uses attribute-set: pin, so
the id in both requests is DPLL_A_PIN_ID, not a device id; there is no
reachable "target dpll" attribute at all (DPLL_A_PIN_PARENT_ID is in
neither list). dpll_nl_pin_get_dumpit() does not look at the request,
it walks dpll_pin_xa from ctx->idx and emits every registered,
available pin, and there is no dump start callback to consume an id
either.

So the generated dpll_pin_get_dump() sends an id, gets the full list
back and reports no error. Drop the id from the dump request and the
two targeting claims from the doc.

Present since commit 3badff3a25d8 ("dpll: spec: Add Netlink spec in
YAML").
Same caveat as for pin-set: sending DPLL_A_PIN_ID in a pin-get dump now
fails validation instead of being ignored.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 Documentation/netlink/specs/dpll.yaml | 11 +++--------
 drivers/dpll/dpll_nl.c                | 17 +++++------------
 2 files changed, 8 insertions(+), 20 deletions(-)

diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml
index 93e546ba1f56..e2ca4df5699a 100644
--- a/Documentation/netlink/specs/dpll.yaml
+++ b/Documentation/netlink/specs/dpll.yaml
@@ -701,11 +701,9 @@ doc: DPLL subsystem.
       doc: |
         Get list of pins and its attributes.
 
-        - dump request without any attributes given - list all the pins in the
-          system
-        - dump request with target dpll - list all the pins registered with
-          a given dpll device
-        - do request with target dpll and target pin - single pin attributes
+        - dump request - list all the registered, available pins in the
+          system, the request takes no attributes
+        - do request with target pin - single pin attributes
       attribute-set: pin
       flags: [admin-perm]
 
@@ -742,9 +740,6 @@ doc: DPLL subsystem.
             - measured-frequency
 
       dump:
-        request:
-          attributes:
-            - id
         reply: *pin-attrs
 
     -
diff --git a/drivers/dpll/dpll_nl.c b/drivers/dpll/dpll_nl.c
index 3bdabbf2b931..fa09b524a4a0 100644
--- a/drivers/dpll/dpll_nl.c
+++ b/drivers/dpll/dpll_nl.c
@@ -65,12 +65,7 @@ static const struct nla_policy dpll_pin_id_get_nl_policy[DPLL_A_PIN_TYPE + 1] =
 };
 
 /* DPLL_CMD_PIN_GET - do */
-static const struct nla_policy dpll_pin_get_do_nl_policy[DPLL_A_PIN_ID + 1] = {
-	[DPLL_A_PIN_ID] = { .type = NLA_U32, },
-};
-
-/* DPLL_CMD_PIN_GET - dump */
-static const struct nla_policy dpll_pin_get_dump_nl_policy[DPLL_A_PIN_ID + 1] = {
+static const struct nla_policy dpll_pin_get_nl_policy[DPLL_A_PIN_ID + 1] = {
 	[DPLL_A_PIN_ID] = { .type = NLA_U32, },
 };
 
@@ -133,16 +128,14 @@ static const struct genl_split_ops dpll_nl_ops[] = {
 		.pre_doit	= dpll_pin_pre_doit,
 		.doit		= dpll_nl_pin_get_doit,
 		.post_doit	= dpll_pin_post_doit,
-		.policy		= dpll_pin_get_do_nl_policy,
+		.policy		= dpll_pin_get_nl_policy,
 		.maxattr	= DPLL_A_PIN_ID,
 		.flags		= GENL_ADMIN_PERM | GENL_CMD_CAP_DO,
 	},
 	{
-		.cmd		= DPLL_CMD_PIN_GET,
-		.dumpit		= dpll_nl_pin_get_dumpit,
-		.policy		= dpll_pin_get_dump_nl_policy,
-		.maxattr	= DPLL_A_PIN_ID,
-		.flags		= GENL_ADMIN_PERM | GENL_CMD_CAP_DUMP,
+		.cmd	= DPLL_CMD_PIN_GET,
+		.dumpit	= dpll_nl_pin_get_dumpit,
+		.flags	= GENL_ADMIN_PERM | GENL_CMD_CAP_DUMP,
 	},
 	{
 		.cmd		= DPLL_CMD_PIN_SET,
-- 
2.55.0

[PATCH net-next 4/4] MAINTAINERS: dpll: add the netlink spec

[Jakub Kicinski]

get_maintainer.pl on Documentation/netlink/specs/dpll.yaml returns only
the YNL and NETWORKING [GENERAL] entries, so a change to the DPLL uAPI
description does not CC any of the DPLL maintainers. Ten other families
(binder, dev-energymodel, ethtool, handshake, mptcp_pm, ovpn, psp,
team, wireguard, rt-*) already list their spec explicitly.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index b23fb6f2f4ef..b000853829b5 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7919,6 +7919,7 @@ S:	Supported
 F:	Documentation/devicetree/bindings/dpll/dpll-device.yaml
 F:	Documentation/devicetree/bindings/dpll/dpll-pin.yaml
 F:	Documentation/driver-api/dpll.rst
+F:	Documentation/netlink/specs/dpll.yaml
 F:	drivers/dpll/
 F:	include/linux/dpll.h
 F:	include/uapi/linux/dpll.h
-- 
2.55.0

Re: [PATCH net-next 1/4] netlink: specs: dpll: add clock-quality-level to the device-get reply

[Vadim Fedorenko]

On 04/09/2026 20:10, Jakub Kicinski wrote:
> dpll_device_get_one() calls dpll_msg_add_clock_quality_level(), which
> puts DPLL_A_CLOCK_QUALITY_LEVEL into every device-get reply, dump entry
> and device-*-ntf of a device whose driver implements
> clock_quality_level_get() - mlx5 does. The &dev-attrs anchor lists 12
> attributes and not this one, so struct dpll_device_get_rsp has no field
> for it, dpll_device_get_rsp_parse() drops it and dpll.rst does not
> document it.
> 
> The attribute itself is correctly declared in the dpll attribute set,
> only the reply list was missing an entry. Missing since commit
> a1afb959add1 ("dpll: add clock quality level attribute and op").
> 
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
>   Documentation/netlink/specs/dpll.yaml | 1 +
>   1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/netlink/specs/dpll.yaml b/Documentation/netlink/specs/dpll.yaml
> index cdc8c7b456df..64a45088c027 100644
> --- a/Documentation/netlink/specs/dpll.yaml
> +++ b/Documentation/netlink/specs/dpll.yaml
> @@ -632,6 +632,7 @@ doc: DPLL subsystem.
>               - mode-supported
>               - lock-status
>               - lock-status-error
> +            - clock-quality-level
>               - temp
>               - clock-id
>               - type

Reviewed-by: Vadim Fedorenko <vadim.fedorenko@linux.dev>