Commit 2ac5ef3b authored by Simon Ser's avatar Simon Ser

drm: document drm_mode_get_connector

Document how to perform a GETCONNECTOR ioctl. Document the various
struct fields. Also document how to perform a forced probe, and when
should user-space do it.
Signed-off-by: default avatarSimon Ser <contact@emersion.fr>
Reviewed-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Cc: Pekka Paalanen <ppaalanen@gmail.com>
Link: https://patchwork.freedesktop.org/patch/msgid/4NxrTtynzPiPX4SOCzxmA1sRB8fVLfeiabVpi5j3Y@cp7-web-041.plabs.ch
parent 65f8453d
......@@ -368,27 +368,95 @@ enum drm_mode_subconnector {
#define DRM_MODE_CONNECTOR_WRITEBACK 18
#define DRM_MODE_CONNECTOR_SPI 19
/**
* struct drm_mode_get_connector - Get connector metadata.
*
* User-space can perform a GETCONNECTOR ioctl to retrieve information about a
* connector. User-space is expected to retrieve encoders, modes and properties
* by performing this ioctl at least twice: the first time to retrieve the
* number of elements, the second time to retrieve the elements themselves.
*
* To retrieve the number of elements, set @count_props and @count_encoders to
* zero, set @count_modes to 1, and set @modes_ptr to a temporary struct
* drm_mode_modeinfo element.
*
* To retrieve the elements, allocate arrays for @encoders_ptr, @modes_ptr,
* @props_ptr and @prop_values_ptr, then set @count_modes, @count_props and
* @count_encoders to their capacity.
*
* Performing the ioctl only twice may be racy: the number of elements may have
* changed with a hotplug event in-between the two ioctls. User-space is
* expected to retry the last ioctl until the number of elements stabilizes.
* The kernel won't fill any array which doesn't have the expected length.
*
* **Force-probing a connector**
*
* If the @count_modes field is set to zero, the kernel will perform a forced
* probe on the connector to refresh the connector status, modes and EDID.
* A forced-probe can be slow and the ioctl will block. A force-probe can cause
* flickering and temporary freezes, so it should not be performed
* automatically.
*
* User-space shouldn't need to force-probe connectors in general: the kernel
* will automatically take care of probing connectors that don't support
* hot-plug detection when appropriate. However, user-space may force-probe
* connectors on user request (e.g. clicking a "Scan connectors" button, or
* opening a UI to manage screens).
*/
struct drm_mode_get_connector {
/** @encoders_ptr: Pointer to ``__u32`` array of object IDs. */
__u64 encoders_ptr;
/** @modes_ptr: Pointer to struct drm_mode_modeinfo array. */
__u64 modes_ptr;
/** @props_ptr: Pointer to ``__u32`` array of property IDs. */
__u64 props_ptr;
/** @prop_values_ptr: Pointer to ``__u64`` array of property values. */
__u64 prop_values_ptr;
/** @count_modes: Number of modes. */
__u32 count_modes;
/** @count_props: Number of properties. */
__u32 count_props;
/** @count_encoders: Number of encoders. */
__u32 count_encoders;
__u32 encoder_id; /**< Current Encoder */
__u32 connector_id; /**< Id */
/** @encoder_id: Object ID of the current encoder. */
__u32 encoder_id;
/** @connector_id: Object ID of the connector. */
__u32 connector_id;
/**
* @connector_type: Type of the connector.
*
* See DRM_MODE_CONNECTOR_* defines.
*/
__u32 connector_type;
/**
* @connector_type_id: Type-specific connector number.
*
* This is not an object ID. This is a per-type connector number. Each
* (type, type_id) combination is unique across all connectors of a DRM
* device.
*/
__u32 connector_type_id;
/**
* @connection: Status of the connector.
*
* See enum drm_connector_status.
*/
__u32 connection;
__u32 mm_width; /**< width in millimeters */
__u32 mm_height; /**< height in millimeters */
/** @mm_width: Width of the connected sink in millimeters. */
__u32 mm_width;
/** @mm_height: Height of the connected sink in millimeters. */
__u32 mm_height;
/**
* @subpixel: Subpixel order of the connected sink.
*
* See enum subpixel_order.
*/
__u32 subpixel;
/** @pad: Padding, must be zero. */
__u32 pad;
};
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment