Documentation for the raw property value traits

Author: apparentlymart

examples/modesetting-atomic.rs

@@ -72,52 +72,52 @@ fn display_demo(card: &mut Card) -> Result<(), Error> {
         req.set_property(
             ObjectId::Connector(output.conn_id),
             output.conn_prop_ids.crtc_id,
-            output.crtc_id as u64,
+            output.crtc_id,
         );
         req.set_property(
             ObjectId::Crtc(output.crtc_id),
             output.crtc_prop_ids.active,
-            1_u64,
+            true,
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.fb_id,
-            output.db.framebuffer_id() as u64,
+            output.db.framebuffer_id(),
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.crtc_id,
-            output.crtc_id as u64,
+            output.crtc_id,
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.crtc_x,
-            0_u64,
+            0,
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.crtc_y,
-            0_u64,
+            0,
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.crtc_w,
-            output.db.width() as u64,
+            output.db.width(),
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.crtc_h,
-            output.db.height() as u64,
+            output.db.height(),
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.src_x,
-            0_u64,
+            0,
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),
             output.plane_prop_ids.src_y,
-            0_u64,
+            0,
         );
         req.set_property(
             ObjectId::Plane(output.plane_id),

src/modeset/props.rs

@@ -233,11 +233,29 @@ impl ObjectPropEnumMember {
     }
 }
 
+/// Trait implemented by types that can be borrowed as raw property values.
+///
+/// For types that represent references to other objects already known by
+/// the kernel, such as property blobs, the caller must keep the original
+/// object live for as long as the result is being used in requests to the
+/// kernel.
 pub trait AsRawPropertyValue {
     fn as_raw_property_value(&self) -> u64;
 }
 
+/// Trait implemented by types that can be converted into raw property values
+/// while transferring ownership.
+///
+/// This is an extension of [`AsRawPropertyValue`] for situations where the
+/// recipient is taking ownership of the implementing object, so that the
+/// object can be kept live long enough to use its raw representation.
 pub trait IntoRawPropertyValue: AsRawPropertyValue {
+    /// Return the raw `u64` representation to send to the kernel along with
+    /// an optional object that needs to be kept live in order for that
+    /// raw result to remain valid.
+    ///
+    /// The first result should typically be the same as would be returned
+    /// from [`AsRawPropertyValue::as_raw_property_value`].
     fn into_raw_property_value(self) -> (u64, Option<Box<dyn core::any::Any>>);
 }