Re: [PATCH RFC 02/20] ctlv: Add the UAPI wire format and family API

[Jonathan Cameron <jic23@kernel.org>]

On Thu, 15 Oct 2026 16:50:35 +0200
Jiri Pirko <jiri@resnulli.us> wrote:

> From: Jiri Pirko <jiri@nvidia.com>
> 
> Define CTLV's common TLV transport, ioctl, event records, identifiers
> and limits. Add the in-kernel API used by family implementations and
> generated code.
> 
> Assisted-by: Cursor: GPT-5.6 Sol
> Assisted-by: Cursor: Claude Opus 5.5
> Signed-off-by: Jiri Pirko <jiri@nvidia.com>
Minor stuff only.  Some of it moaning about toys we don't get in uapi
headers that make kernel code 'so elegant' :)

> diff --git a/include/linux/ctlv_family.h b/include/linux/ctlv_family.h
> new file mode 100644
> index 000000000000..1ae4d3a536f7
> --- /dev/null
> +++ b/include/linux/ctlv_family.h

FWIW I fully agree with Jason that sometimes it is worth burning
some lines and even duplicating things a bit to avoid too many
complex macros.  I didn't have anything to add to comments on this file
at this point.  Will see how new version looks!


> diff --git a/include/uapi/linux/ctlv.h b/include/uapi/linux/ctlv.h
> new file mode 100644
> index 000000000000..6bc0d1a296e6
> --- /dev/null
> +++ b/include/uapi/linux/ctlv.h
> @@ -0,0 +1,183 @@
> +/* SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) */
> +/*
> + * Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES
> + *
> + * CTLV transport UAPI: the TLV wire format, the op-execution ioctl, the event
> + * record header and transport limits. Schema-free; a family's constants
> + * are generated into <linux/<family>_gen.h>, the root family's into
> + * <linux/ctlv_gen.h>.
> + */
> +#ifndef _UAPI_LINUX_CTLV_H
> +#define _UAPI_LINUX_CTLV_H
> +
> +#include <linux/ioctl.h>
> +#include <linux/types.h>
> +
> +/**
> + * struct ctlv_attr - Attr header.
> + * @len: this header plus its payload, excluding this attr's trailing padding
> + * @flags: CTLV_ATTR_F_* bits
> + * @attr_id: complete attr ID, or CTLV_ATTR_ROOT for a message root
> + *
> + * Attrs are aligned to CTLV_ALIGNTO, which is why @attr_id is __aligned_u64: a
> + * 32-bit ABI would otherwise align this structure to four bytes. A nested
> + * payload is the concatenation of CTLV_ALIGN(child.len) bytes per child, so
> + * child padding counts inside the containing attr's @len while a leaf's own

Whilst I get what you mean, leaf doesn't feel like a clear concept in this
comment block.  Maybe 'this attrs own padding does not.' or something like that?

> + * padding does not. Scalar payloads are native-endian. Within each request
> + * root or nest, occurrences of one @attr_id are contiguous; different IDs
> + * otherwise have no required order.
> + */
> +struct ctlv_attr {
> +	__u32 len;
> +	__u32 flags;
> +	__aligned_u64 attr_id;
> +};
> +
> +#define CTLV_ALIGNTO 8
> +#define CTLV_ALIGN(_len) (((_len) + CTLV_ALIGNTO - 1) & ~(CTLV_ALIGNTO - 1))

Could this use __ALIGN_KERNEL() from uapi/linux/const.h?


> +
> +/* Set exactly on root and nested attrs, clear on scalar attrs. */
> +#define CTLV_ATTR_F_NESTED		(1U << 0)
> +/* Query fragments: set on the root and each nest logically open at the end. */
> +#define CTLV_ATTR_F_FRAG_MORE		(1U << 1)
> +/*
> + * A request attr, never the root, that a device whose schema does not declare
> + * its ID skips whole instead of refusing the message. An ID that schema does
> + * declare is held to it wherever it appears, so this asks to be forgiven what
> + * this kernel has never heard of and nothing else.
> + */
> +#define CTLV_ATTR_F_IGNORE_IF_UNKNOWN	(1U << 2)

Doesn't really matter but could use __BITUL() just to hammer home this are single
bits. Places like pci_regs.h have started doing this for new things.



> +/* Implementation limits, not wire-field maxima: raising them is compatible. */
> +
> +/* Request roots, action replies, query reply fragments and event roots. */
> +#define CTLV_MAX_INLINE_MESSAGE_LEN	0x100000	/* 1 MiB */
> +/* Includes the error information root. */
> +#define CTLV_MAX_ERROR_LEN		0x4000		/* 16 KiB */
> +/* The root attr is at depth zero. */
> +#define CTLV_MAX_NEST_DEPTH		32
> +#define CTLV_DEFAULT_QUERY_REPLY_LEN	0x10000		/* 64 KiB */
> +#define CTLV_MAX_EVENT_QUEUE_LEN	0x1000000	/* 16 MiB */

Pity the linux/sizes.h header isn't in UAPI as result is we need
those comments on what the sizes are.  Ah well, never mind.

> +
> +#endif /* _UAPI_LINUX_CTLV_H */