STRUCT V4L2_SUBDEV(9)

💅 struct v4l2_subdev — describes a V4L2 sub-device

okay bestie, welcome to the Kernel API Manual ✨ this one's a whole struct, and it's kind of the main character of V4L2 sub-devices. strap in 💖

🌸 NAME 🌸

struct v4l2_subdev — literally just describes a V4L2 sub-device. that's the vibe check. periodt.

🎀 SYNOPSIS 🎀

no cap, here's the whole thing, exactly as it is:

struct v4l2_subdev {
  #if defined(CONFIG_MEDIA_CONTROLLER);
    struct media_entity entity;
  #endif;
    struct list_head list;
    struct module *owner;
    bool owner_v4l2_dev;
    u32 flags;
    struct v4l2_device *v4l2_dev;
    const struct v4l2_subdev_ops *ops;
    const struct v4l2_subdev_internal_ops *internal_ops;
    struct v4l2_ctrl_handler *ctrl_handler;
    char name[52];
    u32 grp_id;
    void *dev_priv;
    void *host_priv;
    struct video_device *devnode;
    struct device *dev;
    struct fwnode_handle *fwnode;
    struct list_head async_list;
    struct list_head async_subdev_endpoint_list;
    struct v4l2_async_notifier *subdev_notifier;
    struct list_head asc_list;
    struct v4l2_subdev_platform_data *pdata;
    struct mutex *state_lock;
    struct led_classdev *privacy_led;
    struct v4l2_subdev_state *active_state;
    u64 enabled_pads;
    bool s_stream_enabled;
};

🦋 Members 🦋

okay so every single field, one by one, iykyk 👑

entity — pointer to struct media_entity 💫
list — the List of sub-devices 🫶
owner — the owner is the same as the driver's struct device owner. yes, same one.
owner_v4l2_dev — true if the sd->owner matches the owner of v4l2_dev->dev owner. it gets Initialized by v4l2_device_register_subdev. slay.
flags — subdev flags, and the options are giving variety. Can be:
- V4L2_SUBDEV_FL_IS_I2C — Set this flag if this subdev is a i2c device
- V4L2_SUBDEV_FL_IS_SPI — Set this flag if this subdev is a spi device
- V4L2_SUBDEV_FL_HAS_DEVNODE — Set this flag if this subdev needs a device node
- V4L2_SUBDEV_FL_HAS_EVENTS — Set this flag if this subdev generates events
v4l2_dev — pointer to struct v4l2_device 🌈
ops — pointer to struct v4l2_subdev_ops ⭐
internal_ops — pointer to struct v4l2_subdev_internal_ops. and bestie, listen: Never call these internal ops from within a driver! 🚨 fr fr. that's a hard no.
ctrl_handler — the control handler of this subdev. May be NULL. no biggie.
name — Name of the sub-device. but please notice that the name must be unique 👀 like, actually unique. don't come for me.
grp_id — can be used to group similar subdevs. the Value is driver-specific 🎀
dev_priv — pointer to private data 🔒
host_priv — pointer to private data used by the device where the subdev is attached.
devnode — subdev device node 🌸
dev — pointer to the physical device, if any
fwnode — the fwnode_handle of the subdev, usually the same as either dev->of_node->fwnode or dev->fwnode (whichever is non-NULL). whichever one's actually there 💫
async_list — Links this subdev to a global subdev_list or notifier->done_list list.
async_subdev_endpoint_list — List entry in async_subdev_endpoint_entry of struct v4l2_async_subdev_endpoint.
subdev_notifier — a sub-device notifier implicitly registered for the sub-device using v4l2_async_register_subdev_sensor. cute, it registers itself 😌
asc_list — Async connection list, of struct v4l2_async_connection.subdev_entry.
pdata — common part of subdevice platform data
state_lock — a pointer to a lock used for all the subdev's states, set by the driver. this one's optional. if it's NULL, each state instance will get a lock of its own. you get a lock! you get a lock! 🔐
privacy_led — Optional pointer to a LED classdev for the privacy LED for sensors. 🕯️ it's giving "the light is on" energy.
active_state — Active state for the subdev (NULL for subdevs tracking the state internally). Initialized by calling v4l2_subdev_init_finalize. ✨
enabled_pads — Bitmask of enabled pads used by v4l2_subdev_enable_streams and v4l2_subdev_disable_streams helper functions for fallback cases.
s_stream_enabled — Tracks whether streaming has been enabled with s_stream. this is only for call_s_stream internal use. insider info only 🤫

✨ Description ✨

okay so the lore: each instance of a subdev driver should create this struct — either stand-alone, or embedded in a larger struct. both are valid, it's flexible like that 💁‍♀️

and this structure should be initialized by v4l2_subdev_init or one of its variants: v4l2_spi_subdev_init, v4l2_i2c_subdev_init. don't skip the init step bestie, it's not a vibe 💀

🔥 SEE ALSO 🔥

the whole friend group 💜 first up, the Kernel file: ./include/media/v4l2-subdev.h struct — that's the source of truth, go say hi.

and now the extended squad, no one left out:

that's the whole page, you ate it up 💅

and finally, the cute little sign-off: this one lives in ./include/media, it's dated October 2026, and it comes from the Kernel API Manual — that's struct v4l2_subdev(9), mwah 😘🫶

📦 where this page comes from

nixpkgs unstable: linux-manual 7.3.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms