STRUCT V4L2_CTRL_REF(9)

📦 version 7.3.1, in nixpkgs unstable

💅 struct v4l2_ctrl_ref(9) — the control reference, bestie

okay so this is a page straight outta the Kernel API Manual and it's literally all about struct v4l2_ctrl_ref, which is, like, the control reference. yes queen, the whole thing. let's get into it 🎀

✨ SYNOPSIS ✨

here's the struct, in all its glory — no cap, this is character-for-character what you get:

struct v4l2_ctrl_ref {
    struct list_head node;
    struct v4l2_ctrl_ref *next;
    struct v4l2_ctrl *ctrl;
    struct v4l2_ctrl_helper *helper;
    bool from_other_dev;
    bool req_done;
    bool p_req_valid;
    bool p_req_array_enomem;
    u32 p_req_array_alloc_elems;
    u32 p_req_elems;
    union v4l2_ctrl_ptr p_req;
};

🦋 Members 🦋

okay so let's go field by field, because every single one of these matters 💖

  • node — the list node for the sorted list. she's linked, she's ordered, she's iconic.
  • next — single-link list node for the hash. one pointer, one job, slay.
  • ctrl — the actual control information. like, the real deal.
  • helper — pointer to helper struct. used internally in prepare_ext_ctrls function at v4l2-ctrl.c — iykyk, that's where she lives.
  • from_other_dev — if true, then ctrl was defined in another device than the struct v4l2_ctrl_handler. so she's visiting from another dev, we love a crossover moment 🌈
  • req_done — internal flag: if the control handler containing this control reference is bound to a media request, then this is set when the control has been applied. this prevents applying controls from a cluster with multiple controls twice (when the first control of a cluster is applied, they all are). no double-dipping bestie, that's the whole point 💅
  • p_req_valid — if set, then p_req contains the control value for the request.
  • p_req_array_enomem — if set, then p_req is invalid since allocating space for an array failed. attempting to read this value shall result in ENOMEM. only valid if ctrl->is_array is true. 😭 the allocation said no.
  • p_req_array_alloc_elems — the number of elements allocated for the array. only valid if p_req_valid and ctrl->is_array are true.
  • p_req_elems — the number of elements in p_req. this is the same as ctrl->elems, except for dynamic arrays. in that case it is in the range of 1 to p_req_array_alloc_elems. only valid if p_req_valid is true.
  • p_req — if the control handler containing this control reference is bound to a media request, then this points to the value of the control that must be applied when the request is executed, or to the value of the control at the time that the request was completed. if p_req_valid is false, then this control was never set for this request and the control will not be updated when this request is applied. honestly kind of a main character field, the way she carries the request value 🫶

🌸 Description 🌸

each control handler has a list of these refs. periodt.

the list_head is used to keep a sorted-by-control-ID list of all controls, while the next pointer is used to link the control in the hash's bucket. two structures, two purposes, one little struct doing both — that's range, bestie ✨

💜 SEE ALSO 💜

okay this list is LONG and we are NOT skipping a single one, so buckle up 🎀 — kernel file ./include/media/v4l2-ctrls.h plus:

and that's the whole page bestie!! 🫶💖

cute little sign-off: this one lives in ./include/media and the version stamp says October 2026, so she's dated, she's sourced, she's struct v4l2_ctrl_ref(9) and she ate 💅✨🎀

📦 where this page comes from