CTLV compared with the Netlink YAML specs

The kernel already describes Netlink protocols in YAML (Documentation/netlink/specs/, schemas in Documentation/netlink/). CTLV specs look similar on purpose, and differ in ways that follow from CTLV being a character-device transport. This page lines them up. "Netlink" below means the modern genetlink schema, Documentation/netlink/genetlink.yaml; the older genetlink-c, genetlink-legacy and netlink-raw levels add keys on top of it and are mentioned only where they matter.

Common ground

If you know Netlink specs, these will feel familiar.

• A YAML file is the complete description of an interface. A generator produces the UAPI header and kernel-side tables from it, and the kernel validates incoming messages against what the spec declares.
• Messages are trees of typed attributes, with nesting, repetition, integers, strings and binary data.
• Attributes are declared in named collections and referenced by name from operations.
• Enums and flags are declared once and attached to integer attributes.
• Operations come in request/reply, multi-part (dump or query) and unsolicited (notification or event) flavours.
• Names are kebab-case and become upper-case C identifiers.
• Both are validated by a JSON Schema (draft 7) in the tree, with the same %YAML 1.2 header and SPDX first line, and both use the licence expression ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause) in-tree.

Same interface, two specs

The Netlink handshake family (Documentation/netlink/specs/handshake.yaml) lets a TLS handler daemon accept a pending handshake request. Here is its accept command, abridged, and a CTLV spec for an equivalent invented interface.

Netlink

name: handshake
protocol: genetlink
doc: Netlink protocol to request a transport layer security handshake.

definitions:
  -
    type: enum
    name: handler-class
    value-start: 0
    entries: [none, tlshd, max]
  -
    type: enum
    name: auth
    value-start: 0
    entries: [unspec, unauth, psk, x509]

attribute-sets:
  -
    name: x509
    attributes:
      - { name: cert,    type: s32 }
      - { name: privkey, type: s32 }
  -
    name: accept
    attributes:
      - { name: sockfd,        type: s32 }
      - { name: handler-class, type: u32, enum: handler-class }
      - { name: timeout,       type: u32 }
      - { name: auth-mode,     type: u32, enum: auth }
      - { name: peer-identity, type: u32, multi-attr: true }
      - { name: certificate,   type: nest, nested-attributes: x509,
          multi-attr: true }
  -
    name: done
    attributes:
      - name: status
        type: u32
        checks: { max: max-errno }

operations:
  list:
    -
      name: accept
      doc: Handler retrieves next queued handshake request
      attribute-set: accept
      flags: [admin-perm]
      do:
        request:
          attributes: [handler-class]
        reply:
          attributes: [sockfd, timeout, auth-mode,
                       peer-identity, certificate]

CTLV

family:
  name: ctlv-handshake
  inherits: ctlv

enums:
  - name: handler-class
    values: [ tlshd ]
  - name: auth
    values: [ unauth, psk, x509 ]

attr-groups:
  - name: handshake
    attrs:
      - name: sockfd
        type: sint
      - name: handler-class
        enum: handler-class
      - name: timeout
        type: uint
      - name: auth-mode
        enum: auth
      - name: peer-identity
        type: uint
        max-occurrences: 8
      - name: certificate
        attrs: x509
        max-occurrences: 4
      - name: cert
        type: sint
      - name: privkey
        type: sint
      - name: status
        type: uint
        max: 4095

attr-sets:
  - name: x509
    attrs: [ handshake.cert, handshake.privkey ]
  - name: accept-request
    attrs: handshake.handler-class
  - name: accept-reply
    attrs: [ handshake.sockfd, handshake.timeout, handshake.auth-mode ]
    optional-attrs: [ handshake.peer-identity, handshake.certificate ]

ops:
  - name: accept
    type: action
    request:
      attrs: accept-request
    reply:
      attrs: accept-reply

The CTLV spec passes the CTLV validator once registered. Points worth noticing:

• Netlink puts the attribute list for a message on the operation (request.attributes); CTLV names an attr set and lets the set decide which attributes are required and which are optional.
• Netlink's multi-attr: true says "may repeat" with no bound. CTLV's max-occurrences states the bound, and the bound feeds the generated message-length limit.
• The Netlink spec requires doc strings; CTLV specs carry comments instead.
• Netlink's admin-perm is a capability check. CTLV has no counterpart; access is decided by how the device node was opened (fd-access) and by the node's permissions.
• Netlink's enums begin at 0 unless told otherwise, and carry unspec entries by convention. CTLV enums always begin at 1 with 0 reserved, so no placeholder is needed.
• The 8-bit, 16-bit and 32-bit choices disappear: u32 and s32 both become 64-bit uint and sint, narrowed with min/max where needed.

At a glance

Identity and structure

Attributes

Declaring and using

Both languages separate declaring an attribute from deciding where it appears, but at different granularity.

Numbering

CTLV's absence of value overrides means a CTLV spec file is its own numbering: moving or deleting a declaration changes IDs, which the ABI check reports.

Type mapping

Validation constraints

Operations

Events and notifications

Evolution and tooling

Key-by-key map

Closest equivalents. A dash means there is no counterpart.

Reading across

Most differences trace back to two facts.

• CTLV owns the whole stack for its devices. It therefore pins identity (registry), computes and bounds every message size, rejects what the schema does not place, and checks its own history. Netlink specs describe a protocol that mostly already exists in C and has to accommodate legacy, so they offer more escape hatches (value, byte order, dont-validate, header and constant imports, four schema levels) and fewer guarantees.
• CTLV devices form families that extend each other. Inheritance, stubs and the root family's introspection exist for that. A Netlink family stands alone.

Porting an interface from a Netlink spec to CTLV therefore mostly means collapsing integer widths to uint/sint with ranges, turning each operation's attribute list into an attr set with explicit required and optional members, replacing multi-attr with a bound, replacing multicast groups with event operations, and deciding what each operation's fd-access should be.