STRUCT DRM_BRIDGE_FUNCS(9)

💅 NAME

struct drm_bridge_funcs — the drm_bridge control functions, aka the whole personality of a bridge 👑

ok so real quick, bestie: this is the struct drm_bridge_funcs(9) page from the Kernel API Manual, and it's a big one, so we're doing it in parts. Part 1 is right here. Buckle up 💖

✨ SYNOPSIS ✨

struct drm_bridge_funcs {
    int (*attach)(struct drm_bridge *bridge, struct drm_encoder
*encoder, enum drm_bridge_attach_flags flags);
    void (*destroy)(struct drm_bridge *bridge);
    void (*detach)(struct drm_bridge *bridge);
    enum drm_mode_status (*mode_valid)(struct drm_bridge *bridge, const
struct drm_display_info *info, const struct drm_display_mode *mode);
    bool (*mode_fixup)(struct drm_bridge *bridge, const struct
drm_display_mode *mode, struct drm_display_mode *adjusted_mode);
    void (*mode_set)(struct drm_bridge *bridge, const struct
drm_display_mode *mode, const struct drm_display_mode *adjusted_mode);
    void (*atomic_pre_enable)(struct drm_bridge *bridge, struct
drm_atomic_commit *state);
    void (*atomic_enable)(struct drm_bridge *bridge, struct
drm_atomic_commit *state);
    void (*atomic_disable)(struct drm_bridge *bridge, struct
drm_atomic_commit *state);
    void (*atomic_post_disable)(struct drm_bridge *bridge, struct
drm_atomic_commit *state);
    struct drm_bridge_state *(*atomic_duplicate_state)(struct drm_bridge
*bridge);
    void (*atomic_destroy_state)(struct drm_bridge *bridge, struct
drm_bridge_state *state);
    u32 *(*atomic_get_output_bus_fmts)(struct drm_bridge *bridge, struct
drm_bridge_state *bridge_state, struct drm_crtc_state *crtc_state,
struct drm_connector_state *conn_state, unsigned int *num_output_fmts);
    u32 *(*atomic_get_input_bus_fmts)(struct drm_bridge *bridge, struct
drm_bridge_state *bridge_state, struct drm_crtc_state *crtc_state,
struct drm_connector_state *conn_state, u32 output_fmt, unsigned int
*num_input_fmts);
    int (*atomic_check)(struct drm_bridge *bridge, struct
drm_bridge_state *bridge_state, struct drm_crtc_state *crtc_state,
struct drm_connector_state *conn_state);
    struct drm_bridge_state *(*atomic_create_state)(struct drm_bridge
*bridge);
    enum drm_connector_status (*detect)(struct drm_bridge *bridge,
struct drm_connector *connector);
    int (*get_modes)(struct drm_bridge *bridge, struct drm_connector
*connector);
    const struct drm_edid *(*edid_read)(struct drm_bridge *bridge,
struct drm_connector *connector);
    void (*hpd_notify)(struct drm_bridge *bridge, struct drm_connector
*connector, enum drm_connector_status status);
    void (*hpd_enable)(struct drm_bridge *bridge);
    void (*hpd_disable)(struct drm_bridge *bridge);
    enum drm_mode_status (*hdmi_tmds_char_rate_valid)(const struct
drm_bridge *bridge, const struct drm_display_mode *mode, unsigned long
long tmds_rate);
    int (*hdmi_clear_avi_infoframe)(struct drm_bridge *bridge);
    int (*hdmi_write_avi_infoframe)(struct drm_bridge *bridge, const u8
*buffer, size_t len);
    int (*hdmi_clear_hdmi_infoframe)(struct drm_bridge *bridge);
    int (*hdmi_write_hdmi_infoframe)(struct drm_bridge *bridge, const u8
*buffer, size_t len);
    int (*hdmi_clear_hdr_drm_infoframe)(struct drm_bridge *bridge);
    int (*hdmi_write_hdr_drm_infoframe)(struct drm_bridge *bridge, const
u8 *buffer, size_t len);
    int (*hdmi_clear_spd_infoframe)(struct drm_bridge *bridge);
    int (*hdmi_write_spd_infoframe)(struct drm_bridge *bridge, const u8
*buffer, size_t len);
    int (*hdmi_clear_audio_infoframe)(struct drm_bridge *bridge);
    int (*hdmi_write_audio_infoframe)(struct drm_bridge *bridge, const
u8 *buffer, size_t len);
    int (*hdmi_audio_startup)(struct drm_bridge *bridge, struct
drm_connector *connector);
    int (*hdmi_audio_prepare)(struct drm_bridge *bridge, struct
drm_connector *connector, struct hdmi_codec_daifmt *fmt, struct
hdmi_codec_params *hparms);
    void (*hdmi_audio_shutdown)(struct drm_bridge *bridge, struct
drm_connector *connector);
    int (*hdmi_audio_mute_stream)(struct drm_bridge *bridge, struct
drm_connector *connector, bool enable, int direction);
    int (*hdmi_cec_init)(struct drm_bridge *bridge, struct drm_connector
*connector);
    int (*hdmi_cec_enable)(struct drm_bridge *bridge, bool enable);
    int (*hdmi_cec_log_addr)(struct drm_bridge *bridge, u8
logical_addr);
    int (*hdmi_cec_transmit)(struct drm_bridge *bridge, u8 attempts, u32
signal_free_time, struct cec_msg *msg);
    int (*dp_audio_startup)(struct drm_bridge *bridge, struct
drm_connector *connector);
    int (*dp_audio_prepare)(struct drm_bridge *bridge, struct
drm_connector *connector, struct hdmi_codec_daifmt *fmt, struct
hdmi_codec_params *hparms);
    void (*dp_audio_shutdown)(struct drm_bridge *bridge, struct
drm_connector *connector);
    int (*dp_audio_mute_stream)(struct drm_bridge *bridge, struct
drm_connector *connector, bool enable, int direction);
    void (*debugfs_init)(struct drm_bridge *bridge, struct dentry
*root);
};

look at all those function pointers 😭 it's giving "overachiever who takes every AP class." Anyway 💅

🎀 MEMBERS 🎀

🌸 `attach`

So whenever our bridge is getting attached to a drm_encoder, this callback fires. The flags argument tunes the behaviour of the attach operation (peep DRM_BRIDGE_ATTACH_* for the deets, iykyk).

The attach callback is optional.

RETURNS:

Zero on success, error code on failure. classic.

🌸 `destroy`

Called when the bridge is about to be deallocated. it's the goodbye callback 🥺

The destroy callback is optional.

🌸 `detach`

Fires whenever our bridge is being detached from a drm_encoder. breaking up is hard to do etc etc 💔

The detach callback is optional.

🌸 `mode_valid`

This one's a vibe check for modes — it checks if a specific mode is actually valid in this bridge. Implement it if your bridge has some sort of restriction on the modes it can display. For example, a given bridge may be responsible to set a clock value. If the clock can not produce all the values for the available modes, then this callback can be used to restrict the number of modes to only the ones that can be displayed. slay, filtering ✨

This hook is used by the probe helpers to filter the mode list in drm_helper_probe_single_connector_modes, and it's also used by the atomic helpers to validate modes supplied by userspace in drm_atomic_helper_check_modeset.

The mode_valid callback is optional.

NOTE: Since this function is both called from the check phase of an atomic commit, and the mode validation in the probe paths, it is not allowed to look at anything else but the passed-in mode, and validate it against configuration-invariant hardware constraints. Any further limits which depend upon the configuration can only be checked in mode_fixup. no peeking at other state, bestie 🚫👀

RETURNS:

drm_mode_status Enum

🌸 `mode_fixup`

Validate and adjust a mode — multitasking queen 👑 The parameter mode is the display mode that should be fed to the next element in the display chain, either the final drm_connector or the next drm_bridge. The parameter adjusted_mode is the input mode the bridge requires. It can be modified by this callback and does not need to match mode. See also drm_crtc_state.adjusted_mode for more details.

This is the only hook that allows a bridge to reject a modeset. Iconic. So if this function passes, all other callbacks must succeed for this configuration.

The mode_fixup callback is optional. drm_bridge_funcs.mode_fixup is not called when drm_bridge_funcs.atomic_check is implemented, so only one of them should be provided. pick a lane 🫶

NOTE: This function is called in the check phase of atomic modesets, which can be aborted for any reason (including on userspace's request to just check whether a configuration would be possible). Drivers MUST NOT touch any persistent state (hardware or software) or data structures except the passed in state parameter. fr fr, hands off 🖐️

Also beware that userspace can request its own custom modes, neither core nor helpers filter modes to the list of probe modes reported by the GETCONNECTOR IOCTL and stored in drm_connector.modes. To ensure that modes are filtered consistently, put any bridge constraints and limits checks into mode_valid.

RETURNS:

True if an acceptable configuration is possible, false if the modeset operation should be rejected.

🌸 `mode_set`

This callback should set the given mode on the bridge. It is called after the mode_set callback for the preceding element in the display pipeline has been called already. If the bridge is the first element, then this would be drm_encoder_helper_funcs.mode_set. The display pipe (i.e. clocks and timing signals) is off when this function is called. lights off, no cap 💀

The adjusted_mode parameter is the mode output by the CRTC for the first bridge in the chain. It can be different from the mode parameter that contains the desired mode for the connector at the end of the bridges chain — for instance when the first bridge in the chain performs scaling. The adjusted mode is mostly useful for the first bridge in the chain and is likely irrelevant for the other bridges.

For atomic drivers the adjusted_mode is the mode stored in drm_crtc_state.adjusted_mode.

NOTE: This is deprecated, do not use! New drivers shall set their mode in the drm_bridge_funcs.atomic_enable operation. seriously, we're begging 🙈

🌸 `atomic_pre_enable`

This callback should enable the bridge. It is called right before the preceding element in the display pipe is enabled. If the preceding element is a bridge, that means it's called before that bridge's atomic_pre_enable or pre_enable function. If the preceding element is a drm_encoder, it's called right before the encoder's drm_encoder_helper_funcs.atomic_enable hook.

The display pipe (i.e. clocks and timing signals) feeding this bridge will not yet be running when this callback is called. The bridge must not enable the display link feeding the next bridge in the chain (if there is one) when this callback is called. don't get ahead of yourself 💅

The atomic_pre_enable callback is optional.

🌸 `atomic_enable`

This callback should enable the bridge. It is called right after the preceding element in the display pipe is enabled. If the preceding element is a bridge, that means it's called after that bridge's atomic_enable or enable function. If the preceding element is a drm_encoder, it's called right after the encoder's drm_encoder_helper_funcs.atomic_enable hook.

The bridge can assume that the display pipe (i.e. clocks and timing signals) feeding it is running when this callback is called. And this callback must enable the display link feeding the next bridge in the chain if there is one. that's your job now, bestie 🫡

The atomic_enable callback is optional.

ok we're only like a third of the way through these callbacks 😭 the rest is coming in part 2, don't move 🦋

atomic_disable 💅

Okay so this callback is literally the "turn it off" one — it should disable the bridge. It gets called right before the preceding element in the display pipe is disabled. And like, what does "preceding element" mean? Two flavors:

if the preceding element is a bridge, that means this is called before that bridge's atomic_disable or disable vfunc 🫶
if the preceding element is a drm_encoder, it's called right before the drm_encoder_helper_funcs.atomic_disable hook

The bridge can assume the display pipe (i.e. clocks and timing signals) feeding it is still running when this callback fires. So yes bestie, the lights are still on ✨

The atomic_disable callback is optional.

atomic_post_disable 🌸

Same vibe, different timing — this one should also disable the bridge, but it's called right after the preceding element in the display pipe is disabled. Break it down:

if the preceding element is a bridge, it's called after that bridge's atomic_post_disable or post_disable function
if the preceding element is a drm_encoder, it's called right after the encoder's drm_encoder_helper_funcs.atomic_disable hook

The bridge must assume the display pipe (i.e. clocks and timing signals) feeding it is no longer running when this callback is called. Lights off, periodt 💀

The atomic_post_disable callback is optional.

atomic_duplicate_state 🎀

Duplicate the current bridge state object — and good news, that thing is guaranteed to be non-NULL.

The atomic_duplicate_state hook is mandatory if the bridge implements any of the atomic hooks, and should be left unassigned otherwise (like, don't just leave it lying around). For bridges that don't subclass drm_bridge_state, the drm_atomic_helper_bridge_duplicate_state helper function shall be used to implement this hook.

RETURNS: A valid drm_bridge_state object or NULL if the allocation fails.

atomic_destroy_state 🦋

Destroy a bridge state object previously allocated by drm_bridge_funcs.atomic_duplicate_state. Cleanup era 💅

The atomic_destroy_state hook is mandatory if the bridge implements any of the atomic hooks, and should be left unassigned otherwise. For bridges that don't subclass drm_bridge_state, the drm_atomic_helper_bridge_destroy_state helper function shall be used to implement this hook.

atomic_get_output_bus_fmts 🌈

Return the supported bus formats on the output end of a bridge. Some rules, no cap:

The returned array must be allocated with kmalloc and will be freed by the caller. If the allocation fails, NULL should be returned.
num_output_fmts must be set to the returned array size.
Formats listed in the returned array should be listed in decreasing preference order (the core will try all formats until it finds one that works). Obsessed with a good priority list honestly 👑

This method is only called on the last element of the bridge chain as part of the bus format negotiation process that happens in &drm_atomic_bridge_chain_select_bus_fmts. This method is optional. When not implemented, the core will fall back to drm_connector.display_info.bus_formats[0] if drm_connector.display_info.num_bus_formats > 0, or to MEDIA_BUS_FMT_FIXED otherwise.

atomic_get_input_bus_fmts 🧚

Return the supported bus formats on the input end of a bridge, for a specific output bus format. Matchy-matchy 🫶

The returned array must be allocated with kmalloc and will be freed by the caller. If the allocation fails, NULL should be returned. num_input_fmts must be set to the returned array size. Formats listed in the returned array should be listed in decreasing preference order (the core will try all formats until it finds one that works). When the format is not supported, NULL should be returned and num_input_fmts should be set to 0.

This method is called on all elements of the bridge chain as part of the bus format negotiation process that happens in drm_atomic_bridge_chain_select_bus_fmts. This method is optional. When not implemented, the core will bypass bus format negotiation on this element of the bridge without failing, and the previous element in the chain will be passed MEDIA_BUS_FMT_FIXED as its output bus format.

Bridge drivers that need to support being linked to bridges that are not supporting bus format negotiation should handle the output_fmt == MEDIA_BUS_FMT_FIXED case appropriately, by selecting a sensible default value or extracting this information from somewhere else (FW property, drm_display_mode, drm_display_info, ...).

Note: Even if input format selection on the first bridge has no impact on the negotiation process (bus format negotiation stops once we reach the first element of the chain), drivers are expected to return accurate input formats as the input format may be used to configure the CRTC output appropriately. So like, be honest in your answers okay 😭

atomic_check ✨

This method is responsible for checking bridge state correctness. It can also check the state of the surrounding components in chain to make sure the whole pipeline can work properly. It's giving quality control 🎀

drm_bridge_funcs.atomic_check hooks are called in reverse order (from the last to the first bridge).

This method is optional. drm_bridge_funcs.mode_fixup is not called when drm_bridge_funcs.atomic_check is implemented, so only one of them should be provided — pick a lane bestie 💅

If drivers need to tweak drm_bridge_state.input_bus_cfg.flags or drm_bridge_state.output_bus_cfg.flags it should happen in this function. By default the drm_bridge_state.output_bus_cfg.flags field is set to the next bridge drm_bridge_state.input_bus_cfg.flags value or drm_connector.display_info.bus_flags if the bridge is the last element in the chain.

RETURNS: zero if the check passed, a negative error code otherwise.

atomic_create_state 💖

Allocate a pristine, initialized, state for the bridge object and return it. Fresh out the box, untouched, immaculate 🌸

This callback must have no side effects: in particular, the returned state must not be assigned to the object's state pointer and it must not affect the hardware state. Like, hands off the hardware, that's not your business here.

RETURNS:

A new, pristine, bridge state instance or an error pointer on failure.

detect 🔍

Check if anything is attached to the bridge output.

This callback is optional — if not implemented the bridge will be considered as always having a component attached to its output. Bridges that implement this callback shall set the DRM_BRIDGE_OP_DETECT flag in their drm_bridge->ops.

RETURNS:

drm_connector_status indicating the bridge output status.

get_modes 👑

Fill all modes currently valid for the sink into the drm_connector with drm_mode_probed_add.

The get_modes callback is mostly intended to support non-probeable displays such as many fixed panels. Bridges that support reading EDID shall leave get_modes unimplemented and implement the drm_bridge_funcs->edid_read callback instead. Don't do both, it's giving mixed signals 🙈

This callback is optional. Bridges that implement it shall set the DRM_BRIDGE_OP_MODES flag in their drm_bridge->ops.

The connector parameter shall be used for the sole purpose of filling modes, and shall not be stored internally by bridge drivers for future usage. No keeping it in your back pocket 💀

RETURNS:

The number of modes added by calling drm_mode_probed_add.

edid_read 📖

Read the EDID data of the connected display.

The edid_read callback is the preferred way of reporting mode information for a display connected to the bridge output. Bridges that support reading EDID shall implement this callback and leave the get_modes callback unimplemented. Iconic behavior honestly ✨

The caller of this operation shall first verify the output connection status and refrain from reading EDID from a disconnected output. Like, check if anyone's home before you start reading their diary 😭

This callback is optional. Bridges that implement it shall set the DRM_BRIDGE_OP_EDID flag in their drm_bridge->ops.

The connector parameter shall be used for the sole purpose of EDID retrieval, and shall not be stored internally by bridge drivers for future usage.

RETURNS:

An edid structure newly allocated with drm_edid_alloc or returned from drm_edid_read family of functions on success, or NULL otherwise. The caller is responsible for freeing the returned edid structure with drm_edid_free. Yes, you freed it, you own it 🫶

hpd_notify 🔔

Notify the bridge of hot plug detection.

This callback is optional, it may be implemented by bridges that need to be notified of display connection or disconnection for internal reasons. One use case is to reset the internal state of CEC controllers for HDMI bridges. Little internal reset moment, love that for them 💅

hpd_enable 🟢

Enable hot plug detection. From now on the bridge shall call drm_bridge_hpd_notify each time a change is detected in the output connection status, until hot plug detection gets disabled with hpd_disable. You're on call now bestie 📟

This callback is optional and shall only be implemented by bridges that support hot-plug notification without polling. Bridges that implement it shall also implement the hpd_disable callback and set the DRM_BRIDGE_OP_HPD flag in their drm_bridge->ops.

hpd_disable 🔴

Disable hot plug detection. Once this function returns the bridge shall not call drm_bridge_hpd_notify when a change in the output connection status occurs. You're off the clock, go home 💀

This callback is optional and shall only be implemented by bridges that support hot-plug notification without polling. Bridges that implement it shall also implement the hpd_enable callback and set the DRM_BRIDGE_OP_HPD flag in their drm_bridge->ops.

hdmi_tmds_char_rate_valid ⚡

Check whether a particular TMDS character rate is supported by the driver.

This callback is optional and should only be implemented by the bridges that take part in the HDMI connector implementation. Bridges that implement it shall set the DRM_BRIDGE_OP_HDMI flag in their drm_bridge->ops.

Returns:

Either drm_mode_status.MODE_OK or one of the failure reasons in enum drm_mode_status. Fingers crossed for MODE_OK 🤞

hdmi_clear_avi_infoframe 🧹

This callback clears the infoframes in the hardware during commit.

This callback is optional but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI flag in their drm_bridge->ops.

hdmi_write_avi_infoframe ✍️

Program the infoframe into the hardware.

This callback is optional but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI flag in their drm_bridge->ops.

hdmi_clear_hdmi_infoframe 🧽

This callback clears the infoframes in the hardware during commit.

This callback is optional but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI flag in their drm_bridge->ops.

hdmi_write_hdmi_infoframe 🖊️

Program the infoframe into the hardware.

This callback is optional but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI flag in their drm_bridge->ops.

`hdmi_clear_hdr_drm_infoframe`

Okay so this callback clears the infoframes in the hardware during commit. Yes, that's the whole vibe — wipe the HDR infoframe, move on 💅

It's optional BUT (and this is the plot twist) it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_HDR_DRM_INFOFRAME flag in their drm_bridge->ops. Like, if you claimed the flag, bestie, you're in it 🫶

`hdmi_write_hdr_drm_infoframe`

Program the infoframe into the hardware. That's it, that's the job ✨

Optional again, but same deal: it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_HDR_DRM_INFOFRAME flag in their drm_bridge->ops.

`hdmi_clear_spd_infoframe`

This callback clears the infoframes in the hardware during commit 🧹

Optional, but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_SPD_INFOFRAME flag in their drm_bridge->ops.

`hdmi_write_spd_infoframe`

Program the infoframe into the hardware 🎀

Optional, but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_SPD_INFOFRAME flag in their drm_bridge->ops.

`hdmi_clear_audio_infoframe`

Clears the infoframes in the hardware during commit 🫧

Optional, but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_AUDIO flag in their drm_bridge->ops.

`hdmi_write_audio_infoframe`

Program the infoframe into the hardware 🔥

Optional, but it must be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_AUDIO flag in their drm_bridge->ops.

`hdmi_audio_startup`

Called when ASoC starts an audio stream setup 🎧

This one's optional, and it can be implemented by bridges that set the DRM_BRIDGE_OP_HDMI_AUDIO flag in their drm_bridge->ops.