It's not obvious what the fields mean and how they should be used. The most important detail is the link to drm_property.flags, which describes how property types work. v2: document enum drm_mode_property_enum, add ref to "Modeset Base Object Abstraction" (Daniel)
Showing the changes to include/uapi (1 of 2 files). Show all
Unified · Split
| @@ -541,22 +541,74 @@ struct drm_mode_get_connector { · 540 unmodified lines | ||
| 541 | 541 | */ |
| 542 | 542 | #define DRM_MODE_PROP_ATOMIC 0x80000000 |
| 543 | 543 | |
| 544 | +/** | |
| 545 | + * struct drm_mode_property_enum - Description for an enum/bitfield entry. | |
| 546 | + * @value: numeric value for this enum entry. | |
| 547 | + * @name: symbolic name for this enum entry. | |
| 548 | + * | |
| 549 | + * See struct drm_property_enum for details. | |
| 550 | + */ | |
| 544 | 551 | struct drm_mode_property_enum { |
| 545 | 552 | __u64 value; |
| 546 | 553 | char name[DRM_PROP_NAME_LEN]; |
| 547 | 554 | }; |
| 548 | 555 | |
| 556 | +/** | |
| 557 | + * struct drm_mode_get_property - Get property metadata. | |
| 558 | + * | |
| 559 | + * User-space can perform a GETPROPERTY ioctl to retrieve information about a | |
| 560 | + * property. The same property may be attached to multiple objects, see | |
| 561 | + * "Modeset Base Object Abstraction". | |
| 562 | + * | |
| 563 | + * The meaning of the @values_ptr field changes depending on the property type. | |
| 564 | + * See &drm_property.flags for more details. | |
| 565 | + * | |
| 566 | + * The @enum_blob_ptr and @count_enum_blobs fields are only meaningful when the | |
| 567 | + * property has the type &DRM_MODE_PROP_ENUM or &DRM_MODE_PROP_BITMASK. For | |
| 568 | + * backwards compatibility, the kernel will always set @count_enum_blobs to | |
| 569 | + * zero when the property has the type &DRM_MODE_PROP_BLOB. User-space must | |
| 570 | + * ignore these two fields if the property has a different type. | |
| 571 | + * | |
| 572 | + * User-space is expected to retrieve values and enums by performing this ioctl | |
| 573 | + * at least twice: the first time to retrieve the number of elements, the | |
| 574 | + * second time to retrieve the elements themselves. | |
| 575 | + * | |
| 576 | + * To retrieve the number of elements, set @count_values and @count_enum_blobs | |
| 577 | + * to zero, then call the ioctl. @count_values will be updated with the number | |
| 578 | + * of elements. If the property has the type &DRM_MODE_PROP_ENUM or | |
| 579 | + * &DRM_MODE_PROP_BITMASK, @count_enum_blobs will be updated as well. | |
| 580 | + * | |
| 581 | + * To retrieve the elements themselves, allocate an array for @values_ptr and | |
| 582 | + * set @count_values to its capacity. If the property has the type | |
| 583 | + * &DRM_MODE_PROP_ENUM or &DRM_MODE_PROP_BITMASK, allocate an array for | |
| 584 | + * @enum_blob_ptr and set @count_enum_blobs to its capacity. Calling the ioctl | |
| 585 | + * again will fill the arrays. | |
| 586 | + */ | |
| 549 | 587 | struct drm_mode_get_property { |
| 550 | − __u64 values_ptr; /* values and blob lengths */ | |
| 551 | − __u64 enum_blob_ptr; /* enum and blob id ptrs */ | |
| 588 | + /** @values_ptr: Pointer to a ``__u64`` array. */ | |
| 589 | + __u64 values_ptr; | |
| 590 | + /** @enum_blob_ptr: Pointer to a struct drm_mode_property_enum array. */ | |
| 591 | + __u64 enum_blob_ptr; | |
| 552 | 592 | |
| 593 | + /** | |
| 594 | + * @prop_id: Object ID of the property which should be retrieved. Set | |
| 595 | + * by the caller. | |
| 596 | + */ | |
| 553 | 597 | __u32 prop_id; |
| 598 | + /** | |
| 599 | + * @flags: ``DRM_MODE_PROP_*`` bitfield. See &drm_property.flags for | |
| 600 | + * a definition of the flags. | |
| 601 | + */ | |
| 554 | 602 | __u32 flags; |
| 603 | + /** | |
| 604 | + * @name: Symbolic property name. User-space should use this field to | |
| 605 | + * recognize properties. | |
| 606 | + */ | |
| 555 | 607 | char name[DRM_PROP_NAME_LEN]; |
| 556 | 608 | |
| 609 | + /** @count_values: Number of elements in @values_ptr. */ | |
| 557 | 610 | __u32 count_values; |
| 558 | − /* This is only used to count enum values, not blobs. The _blobs is | |
| 559 | − * simply because of a historical reason, i.e. backwards compat. */ | |
| 611 | + /** @count_enum_blobs: Number of elements in @enum_blob_ptr. */ | |
| 560 | 612 | __u32 count_enum_blobs; |
| 561 | 613 | }; |
| 562 | 614 | |