comments: add more explainations to new code

src/backend/drm/egl/mod.rs

@@ -63,7 +63,7 @@ where
 {
     /// Try to create a new `EglDevice` from an open device.
     ///
-    /// Returns an error if the file is no valid device or context 
+    /// Returns an error if the file is no valid device or context
     /// creation was not successful.
     pub fn new<L>(dev: D, logger: L) -> Result<Self>
     where

src/backend/drm/gbm/egl.rs

@@ -88,6 +88,8 @@ unsafe impl<D: RawDevice + 'static> NativeSurface for GbmSurface<D> {
     }
 
     fn swap_buffers(&self) -> ::std::result::Result<(), SwapBuffersError> {
+        // this is save since `eglSwapBuffers` will have been called exactly once
+        // if this is used by our egl module, which is why this trait is unsafe.
         unsafe { self.page_flip() }
     }
 }

src/backend/drm/gbm/mod.rs

@@ -136,6 +136,7 @@ impl<D: RawDevice + ControlDevice + 'static> Device for GbmDevice<D> {
         let drm_surface = Device::create_surface(&mut **self.dev.borrow_mut(), crtc)
             .chain_err(|| ErrorKind::UnderlyingBackendError)?;
 
+        // initialize the surface
         let (w, h) = drm_surface
             .pending_mode()
             .map(|mode| mode.size())
@@ -150,6 +151,7 @@ impl<D: RawDevice + ControlDevice + 'static> Device for GbmDevice<D> {
                 BufferObjectFlags::SCANOUT | BufferObjectFlags::RENDERING,
             ).chain_err(|| ErrorKind::SurfaceCreationFailed)?;
 
+        // initialize a buffer for the cursor image
         let cursor = Cell::new((
             self.dev
                 .borrow()

src/backend/drm/gbm/surface.rs

@@ -284,6 +284,11 @@ pub struct GbmSurface<D: RawDevice + 'static>(pub(super) Rc<GbmSurfaceInternal<D
 impl<D: RawDevice + 'static> GbmSurface<D> {
     /// Flips the underlying buffers.
     ///
+    /// The surface will reported being already flipped until the matching events
+    /// was processed either by calling `GbmDevice::process_events` manually after the flip
+    /// (bad idea performance-wise) or by binding the device to an event-loop by using
+    /// `device_bind`.
+    ///
     /// *Note*: This might trigger a full modeset on the underlying device,
     /// potentially causing some flickering. In that case this operation is
     /// blocking until the crtc is in the desired state.

src/backend/drm/legacy/mod.rs

@@ -60,6 +60,9 @@ impl<A: AsRawFd + 'static> Drop for Dev<A> {
     fn drop(&mut self) {
         info!(self.logger, "Dropping device: {:?}", self.dev_path());
         if self.active.load(Ordering::SeqCst) {
+            // Here we restore the tty to it's previous state.
+            // In case e.g. getty was running on the tty sets the correct framebuffer again,
+            // so that getty will be visible.
             let old_state = self.old_state.clone();
             for (handle, (info, connectors)) in old_state {
                 if let Err(err) = crtc::set(
@@ -113,6 +116,7 @@ impl<A: AsRawFd + 'static> LegacyDrmDevice<A> {
             dev.priviledged = false;
         };
 
+        // enumerate (and save) the current device state
         let res_handles = ControlDevice::resource_handles(&dev).chain_err(|| {
             ErrorKind::DrmDev(format!("Error loading drm resources on {:?}", dev.dev_path()))
         })?;
@@ -138,7 +142,6 @@ impl<A: AsRawFd + 'static> LegacyDrmDevice<A> {
         }
 
         Ok(LegacyDrmDevice {
-            // Open the drm device and create a context based on that
             dev: Rc::new(dev),
             dev_id,
             active,
@@ -182,6 +185,8 @@ impl<A: AsRawFd + 'static> Device for LegacyDrmDevice<A> {
             bail!(ErrorKind::DeviceInactive);
         }
 
+        // Try to enumarate the current state to set the initial state variable correctly
+
         let crtc_info = crtc::Info::load_from_device(self, crtc)
             .chain_err(|| ErrorKind::DrmDev(format!("Error loading crtc info on {:?}", self.dev_path())))?;
 

src/backend/drm/legacy/session.rs

@@ -3,7 +3,7 @@
 //! to an open [`Session`](../../session/trait.Session.html).
 //!
 
-use drm::control::{crtc};
+use drm::control::crtc;
 use drm::Device as BasicDevice;
 use nix::libc::dev_t;
 use nix::sys::stat;
@@ -52,6 +52,8 @@ impl<A: AsRawFd + 'static> SessionObserver for LegacyDrmDeviceObserver<A> {
         if let Some(device) = self.dev.upgrade() {
             if let Some(backends) = self.backends.upgrade() {
                 for surface in backends.borrow().values().filter_map(Weak::upgrade) {
+                    // other ttys that use no cursor, might not clear it themselves.
+                    // This makes sure our cursor won't stay visible.
                     let _ = crtc::clear_cursor(&*device, surface.crtc);
                 }
             }

src/backend/drm/legacy/surface.rs

@@ -131,7 +131,7 @@ impl<A: AsRawFd + 'static> Surface for LegacyDrmSurfaceInternal<A> {
     fn use_mode(&self, mode: Option<Mode>) -> Result<()> {
         let mut pending = self.pending.write().unwrap();
 
-        // check the connectors
+        // check the connectors to see if this mode is supported
         if let Some(mode) = mode {
             for connector in &pending.connectors {
                 if !connector::Info::load_from_device(self, *connector)
@@ -236,6 +236,15 @@ impl<A: AsRawFd + 'static> Drop for LegacyDrmSurfaceInternal<A> {
 /// Open raw crtc utilizing legacy mode-setting
 pub struct LegacyDrmSurface<A: AsRawFd + 'static>(pub(super) Rc<LegacyDrmSurfaceInternal<A>>);
 
+impl<A: AsRawFd + 'static> AsRawFd for LegacyDrmSurface<A> {
+    fn as_raw_fd(&self) -> RawFd {
+        self.0.as_raw_fd()
+    }
+}
+
+impl<A: AsRawFd + 'static> BasicDevice for LegacyDrmSurface<A> {}
+impl<A: AsRawFd + 'static> ControlDevice for LegacyDrmSurface<A> {}
+
 impl<'a, A: AsRawFd + 'static> CursorBackend<'a> for LegacyDrmSurface<A> {
     type CursorFormat = &'a Buffer;
     type Error = Error;

src/backend/drm/mod.rs

@@ -36,8 +36,9 @@
 //!
 
 pub use drm::{
-    control::{connector, crtc, framebuffer, Device as ControlDevice, Mode, ResourceHandles, ResourceInfo},
     Device as BasicDevice,
+    buffer::Buffer,
+    control::{connector, crtc, framebuffer, Mode, ResourceHandles, ResourceInfo, Device as ControlDevice},
 };
 pub use nix::libc::dev_t;
 

src/backend/graphics/gl.rs

@@ -49,7 +49,7 @@ pub trait GLGraphicsBackend {
 ///
 /// This remains valid as long as the underlying `GLGraphicsBackend` is alive
 /// and may only be used in combination with the backend. Using this with any
-/// other gl context may cause undefined behavior.
+/// other gl context *may* cause undefined behavior.
 pub fn load_raw_gl<B: GLGraphicsBackend>(backend: &B) -> Gles2 {
     Gles2::load_with(|s| unsafe { backend.get_proc_address(s) as *const _ })
 }