descriptors(9)

📦 version 7.3.1, in nixpkgs unstable

💅 descriptors

okay bestie, so this page is from the Kernel API Manual, and it's literally the descriptors(9) glow-up guide 🎀 — like, the whole blueprint for the FunctionFS descriptors blob that gets handed to the kernel. it's giving "spreadsheet but make it USB" and honestly? iconic. let's get into it ✨

🌸 Descriptors format

this is the current, main-character layout of the blob, bestie:

  • off 0 · magic (LE32) — literally FUNCTIONFS_DESCRIPTORS_MAGIC_V2 ✨
  • off 4 · length (LE32) — length of the whole data chunk
  • off 8 · flags (LE32) — combination of functionfs_flags
  • eventfd (LE32) — eventfd file descriptor
  • fs_count (LE32) — number of full-speed descriptors
  • hs_count (LE32) — number of high-speed descriptors
  • ss_count (LE32) — number of super-speed descriptors
  • os_count (LE32) — number of MS OS descriptors
  • fs_descrs (Descriptor[]) — list of full-speed descriptors
  • hs_descrs (Descriptor[]) — list of high-speed descriptors
  • ss_descrs (Descriptor[]) — list of super-speed descriptors
  • os_descrs (OSDesc[]) — list of MS OS descriptors
ngl the first three are the only ones with a fixed off in the chart — the rest are just vibing below, no offset given. that's not me skipping them, that's literally how the page is laid out, i'm just the messenger 🫶

and here's the tea ☕ depending on which flags are set, various fields may legitimately be missing in the structure. no, that's not a bug, it's a vibe check.

but 🚨 any flags that are not recognised cause the whole block to be rejected with -ENOSYS. the entire thing. dumped. no cap. so don't be cute with random flag bits 💀

🦋 Legacy descriptors format (deprecated as of 3.14)

okay so this is the old one, and it's deprecated as of 3.14 — so like, respect the history, but don't show up to the party wearing it 🙈

  • off 0 · magic (LE32) — FUNCTIONFS_DESCRIPTORS_MAGIC
  • off 4 · length (LE32) — length of the whole data chunk
  • off 8 · fs_count (LE32) — number of full-speed descriptors
  • off 12 · hs_count (LE32) — number of high-speed descriptors
  • off 16 · fs_descrs (Descriptor[]) — list of full-speed descriptors
  • hs_descrs (Descriptor[]) — list of high-speed descriptors

✨ Endianness, the one rule

all numbers must be in little endian order. all of them. every single one. this is not a suggestion, this is the law 💅

🎀 Descriptor[]

so Descriptor[] is an array of valid USB descriptors, and each one has this format:

  • off 0 · bLength (U8) — length of the descriptor
  • off 1 · bDescriptorType (U8) — descriptor type
  • off 2 · payload — descriptor's payload

👑 OSDesc[]

OSDesc[] is an array of valid MS OS Feature Descriptors, and it has one of two formats — yes, two, pick your fighter:

🌈 Format the first

  • off 0 · interface (U8) — related interface number
  • off 1 · dwLength (U32) — length of the descriptor
  • off 5 · bcdVersion (U16) — currently supported: 1
  • off 7 · wIndex (U16) — currently supported: 4
  • off 9 · bCount (U8) — number of ext. compat.
  • off 10 · Reserved (U8) — 0
  • off 11 · ExtCompat[] — list of ext. compat. d.

🌈 Format the second

  • off 0 · interface (U8) — related interface number
  • off 1 · dwLength (U32) — length of the descriptor
  • off 5 · bcdVersion (U16) — currently supported: 1
  • off 7 · wIndex (U16) — currently supported: 5
  • off 9 · wCount (U16) — number of ext. compat.
  • off 11 · ExtProp[] — list of ext. prop. d.
the difference is lowkey everything: wIndex is 4 vs 5, bCount (U8) vs wCount (U16), and ExtCompat[] vs ExtProp[]. don't mix them up, bestie 😭

🧚 ExtCompat[]

ExtCompat[] is an array of valid Extended Compatibility descriptors, and each one goes like this:

  • off 0 · bFirstInterfaceNumber (U8) — index of the interface or of the 1st interface in an IAD group
  • off 1 · Reserved (U8) — 1
  • off 2 · CompatibleID (U8[8]) — compatible ID string
  • off 10 · SubCompatibleID (U8[8]) — subcompatible ID string
  • off 18 · Reserved (U8[6]) — 0

🍓 ExtProp[]

ExtProp[] is an array of valid Extended Properties descriptors, and this one's a little spicy with the math so bear with me 🌸

  • off 0 · dwSize (U32) — length of the descriptor
  • off 4 · dwPropertyDataType (U32) — 1..7
  • off 8 · wPropertyNameLength (U16) — bPropertyName length (NL)
  • off 10 · bPropertyName (U8[NL]) — name of this property
  • off 10+NL · dwPropertyDataLength (U32) — bPropertyData length (DL)
  • off 14+NL · bProperty (U8[DL]) — payload of this property
see the NL in there? that's the bPropertyName length, so 10+NL and 14+NL slide around depending on how long your property name is. the way that it's variable-length is honestly so real of it 🦋

💜 SEE ALSO

  • Kernel file ./include/uapi/linux/usb/functionfs.h struct usb_dfu_functional_descriptor(9)
  • struct usb_ffs_dmabuf_transfer_req(9)

okay that's the whole page, you ate that 💅 go forth and lay out your descriptors correctly, bestie. this was descriptors(9) from ./include/uapi/linux/usb, dated October 2026, and it slayed fr fr ✨🎀👑

📦 where this page comes from