The Linux Kernel
5.15.0
  • The Linux kernel user’s and administrator’s guide
  • Kernel Build System
  • The Linux kernel firmware guide
  • Open Firmware and Devicetree
  • The Linux kernel user-space API guide
    • No New Privileges Flag
    • Seccomp BPF (SECure COMPuting with filters)
    • Landlock: unprivileged access control
    • unshare system call
    • Speculation Control
    • OpenCAPI (Open Coherent Accelerator Processor Interface)
    • eBPF Userspace API
    • IOCTLs
    • IOMMU Userspace API
    • Linux Media Infrastructure userspace API
    • Netlink Handbook
      • Introduction to Netlink
      • Using Netlink protocol specifications
      • Netlink protocol specifications (in YAML)
      • Netlink spec C code generation
      • Netlink specification support for legacy Generic Netlink families
        • Specification (defined)
        • Other quirks (todo)
    • Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile)
    • VDUSE - “vDPA Device in Userspace”
  • Working with the kernel development community
  • Development tools for the kernel
  • How to write kernel documentation
  • Kernel Hacking Guides
  • Linux Tracing Technologies
  • Kernel Maintainer Handbook
  • fault-injection
  • Kernel Livepatching
  • The Linux driver implementer’s API guide
  • Core API Documentation
  • locking
  • Accounting
  • Block
  • cdrom
  • Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel
  • Integrated Drive Electronics (IDE)
  • Frame Buffer
  • fpga
  • Human Interface Devices (HID)
  • I2C/SMBus Subsystem
  • Industrial I/O
  • ISDN
  • InfiniBand
  • LEDs
  • NetLabel
  • Linux Networking Documentation
  • pcmcia
  • Power Management
  • TCM Virtual Device
  • timers
  • Serial Peripheral Interface (SPI)
  • 1-Wire Subsystem
  • Linux Watchdog Support
  • Linux Virtualization Support
  • The Linux Input Documentation
  • Linux Hardware Monitoring
  • Linux GPU Driver Developer’s Guide
  • Security Documentation
  • Linux Sound Subsystem Documentation
  • Linux Kernel Crypto API
  • Filesystems in the Linux kernel
  • Linux Memory Management Documentation
  • BPF Documentation
  • USB support
  • Linux PCI Bus Subsystem
  • Linux SCSI Subsystem
  • Assorted Miscellaneous Devices Documentation
  • Linux Scheduler
  • MHI
  • Assembler Annotations
  • CPU Architectures
  • Unsorted Documentation
  • Atomic Types
  • Atomic bitops
  • Memory Barriers
  • General notification mechanism
  • Translations
The Linux Kernel
  • Docs »
  • The Linux kernel user-space API guide »
  • Netlink Handbook »
  • Netlink specification support for legacy Generic Netlink families
  • View page source

Netlink specification support for legacy Generic Netlink families¶

This document describes the many additional quirks and properties required to describe older Generic Netlink families which form the genetlink-legacy protocol level.

The spec is a work in progress, some of the quirks are just documented for future reference.

Specification (defined)¶

Attribute type nests¶

New Netlink families should use multi-attr to define arrays. Older families (e.g. genetlink control family) attempted to define array types reusing attribute type to carry information.

For reference the multi-attr array may look like this:

[ARRAY-ATTR]
  [INDEX (optionally)]
  [MEMBER1]
  [MEMBER2]
[SOME-OTHER-ATTR]
[ARRAY-ATTR]
  [INDEX (optionally)]
  [MEMBER1]
  [MEMBER2]

where ARRAY-ATTR is the array entry type.

array-nest¶

array-nest creates the following structure:

[SOME-OTHER-ATTR]
[ARRAY-ATTR]
  [ENTRY]
    [MEMBER1]
    [MEMBER2]
  [ENTRY]
    [MEMBER1]
    [MEMBER2]

It wraps the entire array in an extra attribute (hence limiting its size to 64kB). The ENTRY nests are special and have the index of the entry as their type instead of normal attribute type.

type-value¶

type-value is a construct which uses attribute types to carry information about a single object (often used when array is dumped entry-by-entry).

type-value can have multiple levels of nesting, for example genetlink’s policy dumps create the following structures:

[POLICY-IDX]
  [ATTR-IDX]
    [POLICY-INFO-ATTR1]
    [POLICY-INFO-ATTR2]

Where the first level of nest has the policy index as it’s attribute type, it contains a single nest which has the attribute index as its type. Inside the attr-index nest are the policy attributes. Modern Netlink families should have instead defined this as a flat structure, the nesting serves no good purpose here.

Other quirks (todo)¶

Structures¶

Legacy families can define C structures both to be used as the contents of an attribute and as a fixed message header. The plan is to define the structs in definitions and link the appropriate attrs.

C Arrays¶

Legacy families also use binary attributes to encapsulate C arrays. The sub-type is used to identify the type of scalar to extract.

attributes:
  -
    name: ports
    type: binary
    sub-type: u32

Multi-message DO¶

New Netlink families should never respond to a DO operation with multiple replies, with NLM_F_MULTI set. Use a filtered dump instead.

At the spec level we can define a dumps property for the do, perhaps with values of combine and multi-object depending on how the parsing should be implemented (parse into a single reply vs list of objects i.e. pretty much a dump).

Next Previous

© Copyright The kernel development community.

Built with Sphinx using a theme provided by Read the Docs.