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: Simon Ser contact@emersion.fr Cc: Daniel Vetter daniel@ffwll.ch Cc: Pekka Paalanen ppaalanen@gmail.com --- include/uapi/drm/drm_mode.h | 76 ++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 5 deletions(-)
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h index 5ad10ab2a577..cd97c5671c75 100644 --- a/include/uapi/drm/drm_mode.h +++ b/include/uapi/drm/drm_mode.h @@ -368,27 +368,93 @@ 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. + * + * 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. */ __u32 pad; };
On Thu, Nov 19, 2020 at 2:52 PM Simon Ser contact@emersion.fr wrote:
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: Simon Ser contact@emersion.fr Cc: Daniel Vetter daniel@ffwll.ch Cc: Pekka Paalanen ppaalanen@gmail.com
include/uapi/drm/drm_mode.h | 76 ++++++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 5 deletions(-)
diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h index 5ad10ab2a577..cd97c5671c75 100644 --- a/include/uapi/drm/drm_mode.h +++ b/include/uapi/drm/drm_mode.h @@ -368,27 +368,93 @@ 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.
- 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).
I think we should warn here that force probe can disrupt the UI, hence why it should only be done on user request and not automatically.
- */
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.
Please add & so it becomes a link in the generated docs (and pls check the link goes to the right place).
*/ __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.
Same here.
*/ __u32 subpixel;/** @pad: Padding. */
I think this should have a "Must be zero"?
With the nits addressed: Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch
Thanks a lot for doing this!
__u32 pad;};
-- 2.29.2
On Thursday, November 19, 2020 4:06 PM, Daniel Vetter daniel@ffwll.ch wrote:
/*** @connection: Status of the connector.** See enum drm_connector_status.Please add & so it becomes a link in the generated docs (and pls check the link goes to the right place).
Per [1], just prefixing the enum name with "enum" is enough to generate a link. I prefer this style over the ampersand because it makes the raw text easier to read. The result looks like this [2].
[1]: https://dri.freedesktop.org/docs/drm/doc-guide/kernel-doc.html#cross-referen... [2]: https://l.sr.ht/o7Kb.png
*/ __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.Same here.
This one doesn't generate a link, because enum subpixel_order is undocumented. As soon as it's documented, the link will be created.
The enum is weird in the first place: it has CamelCase members and no drm_ prefix.
With the nits addressed: Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch
I'll fix the other issues you've raised, thanks for the review!
On Fri, Nov 20, 2020 at 9:46 AM Simon Ser contact@emersion.fr wrote:
On Thursday, November 19, 2020 4:06 PM, Daniel Vetter daniel@ffwll.ch wrote:
/*** @connection: Status of the connector.** See enum drm_connector_status.Please add & so it becomes a link in the generated docs (and pls check the link goes to the right place).
Per [1], just prefixing the enum name with "enum" is enough to generate a link. I prefer this style over the ampersand because it makes the raw text easier to read. The result looks like this [2].
Ah nice, I missed that this was updated. We have a ton of & in our kerneldoc that probably could be dropped ... -Daniel
*/ __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.Same here.
This one doesn't generate a link, because enum subpixel_order is undocumented. As soon as it's documented, the link will be created.
The enum is weird in the first place: it has CamelCase members and no drm_ prefix.
With the nits addressed: Reviewed-by: Daniel Vetter daniel.vetter@ffwll.ch
I'll fix the other issues you've raised, thanks for the review!
dri-devel@lists.freedesktop.org
-
Daniel Vetter -
Simon Ser