STRUCT FW_CDEV_ADD_DESCRIPTOR(9)

💅 struct fw_cdev_add_descriptor(9) — Kernel API Manual, but make it make sense

okay so bestie, we're in the Kernel API Manual today and this one is literally about decorating your FireWire node's Configuration ROM. yes, ROM but make it glam 💖

---

✨ NAME ✨

struct fw_cdev_add_descriptor — Add contents to the local node's config ROM

like... you're literally adding stuff to the local node's Configuration ROM. that's the whole gig. 🎀

---

🦋 SYNOPSIS 🦋

struct fw_cdev_add_descriptor {
    __u32 immediate;
    __u32 key;
    __u64 data;
    __u32 length;
    __u32 handle;
 };

this is the struct. it's giving "five fields and a dream." no cap. ⭐

---

🌸 Members 🌸

• immediate — if this is non-zero, it's an immediate key to insert before the pointer. think of it as the little accessory that goes on first. 🎀
• key — the upper 8 bits of the root directory pointer. yes, just the upper 8. the rest is not your business, the kernel handles it. 💅
• data — userspace pointer to the contents of the descriptor block. your data lives here. 🍓
• length — length of the descriptor block data, measured in quadlets. not bytes, bestie, quadlets. write that down. ✨
• handle — handle to the descriptor, and it's written by the kernel, not by you. the kernel does the writing, you just hold the pen case. 🖊️

---

💜 Description 💜

So what this actually does: it adds a descriptor block, and optionally a preceding immediate key, to the local node's Configuration ROM. two-for-one situation, we love to see it. 🫶

The key field specifies the upper 8 bits of the descriptor root directory pointer, and the data and length fields specify the contents. The key should be of the form 0xXX000000. The offset part of the root directory entry will be filled in by the kernel — so don't you dare try to do it yourself, that's kernel main character energy. 👑

If not 0, the immediate field specifies an immediate key which will be inserted before the root directory pointer. zero means "nah, skip it."

immediate, key, and data array elements are CPU-endian quadlets. important detail, do not skip it. 🔥

If successful, the kernel adds the descriptor and writes back a handle to the kernel-side object, to be used for later removal of the descriptor block and immediate key. so keep that handle safe, it's your receipt 🧾✨ And bestie — the kernel will also generate a bus reset to signal the change of the Configuration ROM to other nodes. yes, a whole bus reset. the notification is loud, that's the point. 📣

⚠️ heads up: this ioctl affects the Configuration ROMs of all local nodes. and the ioctl only succeeds on device files which represent a local node. so if it's not a local node device file, it's not happening, periodt. 💀

---

🌈 SEE ALSO 🌈

Kernel file ./include/uapi/linux/firewire-cdev.h — plus the whole extended universe, iykyk:

• struct fw_cdev_event_common(9)
• struct fw_cdev_event_bus_reset(9)
• struct fw_cdev_event_response(9)
• struct fw_cdev_event_response2(9)
• struct fw_cdev_event_request(9)
• struct fw_cdev_event_request2(9)
• struct fw_cdev_event_request3(9)
• struct fw_cdev_event_iso_interrupt(9)
• struct fw_cdev_event_iso_interrupt_mc(9)
• struct fw_cdev_event_iso_resource(9)
• struct fw_cdev_event_phy_packet(9)
• struct fw_cdev_event_phy_packet2(9)
• union fw_cdev_event(9)
• struct fw_cdev_get_info(9)
• struct fw_cdev_send_request(9)
• struct fw_cdev_send_response(9)
• struct fw_cdev_allocate(9)
• struct fw_cdev_deallocate(9)
• struct fw_cdev_initiate_bus_reset(9)
• struct fw_cdev_remove_descriptor(9)
• struct fw_cdev_create_iso_context(9)
• struct fw_cdev_set_iso_channels(9)
• struct fw_cdev_iso_packet(9)
• struct fw_cdev_queue_iso(9)
• struct fw_cdev_start_iso(9)
• struct fw_cdev_stop_iso(9)
• struct fw_cdev_flush_iso(9)
• struct fw_cdev_get_cycle_timer(9)
• struct fw_cdev_get_cycle_timer2(9)
• struct fw_cdev_allocate_iso_resource(9)
• struct fw_cdev_send_stream_packet(9)
• struct fw_cdev_send_phy_packet(9)
• struct fw_cdev_receive_phy_packets(9)

---

and that's the page, bestie!! 🦋 this one lives in ./include/uapi/linux, dated October 2026, and it's filed under struct fw_c...d_descriptor(9) in case you ever need to find it again. go forth and add descriptors responsibly 💅✨🎀