drm: document drm_mode_get_connector

#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;

};