Skip to content
Snippets Groups Projects
  1. Nov 19, 2024
  2. Sep 30, 2024
    • Lyude Paul's avatar
      WIP: drm: Introduce RVKMS! · c470fec9
      Lyude Paul authored
      
      Now that we've added all of the bits that we need for the KMS API, it's
      time to introduce rvkms! This is a port of the VKMS driver to rust, with
      the intent of acting as an example usecase of the KMS bindings that we've
      come up with so far in preparation for writing a display driver for nova.
      
      Currently RVKMS is an extremely bear bones driver - it only registers a
      device and emulates vblanking, but it exercises a good portion of the API
      that we've introduced so far! Eventually I hope to introduce CRC generation
      and maybe writeback connectors like.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      c470fec9
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add Kms::atomic_commit_tail · 49a66dd8
      Lyude Paul authored
      
      A quick note: this is one of my favorite bindings so far :). It sounds way
      overly complicated, but so far actually writing implementations of this in
      rust has been a breeze.
      
      Anyway: RVKMS has a slightly different atomic_commit_tail than normal,
      which means we need to write up some bindings for atomic_commit_tail. This
      is a lot more interesting then it might seem on the surface as implementing
      atomic_commit_tail incorrectly could result in UB. And in general, DRM has
      up until now relied entirely on the programmer to do this correctly through
      implicit ordering requirements.
      
      In the universe of rust though, we want no UB at all! To ensure this, we
      need to make sure that all atomic commit callbacks follow all of these
      requirements:
      
      * Disable/enable modeset commits must happen exactly once
      * A disable modeset must be committed for a resource before an enable
        modeset may be committed for a resource
      * Plane updates must happen exactly once
      * drm_atomic_commit_hw_done() must be called exactly once, and only after
        all commits have been completed.
      * The state may not be mutated after drm_atomic_commit_hw_done() is called
      * Access to the prior atomic states are revoked after
        drm_atomic_commit_hw_done() is called (and our "new" states become "old"
        states)
      
      To handle this, we introduce a number of new objects and types:
      tokens:
      
      * AtomicCommitTail
        Main object for controlling the commit_tail process
        * ModesetsReadyToken
          A single use token indicating that no modesets have been committed with
          the AtomicCommitTail yet
        * commit_modeset_disables() -> DisablesCommittedToken
          This function consumes the ModesetsReadyToken, commits modeset
          disables, and then returns a DisablesCommittedToken
        * commit_modeset_enables() -> EnablesCommittedToken
          This function consumes a DisablesCommittedToken, commits modeset
          enables, and then returns a EnablesCommittedToken
          EnablesCommittedToken - enforcing the disables -> enables order.
        * commit_planes() -> PlaneUpdatesCommittedToken
          Consumes a PlaneUpdatesReadyToken and returns a
          PlaneUpdatesCommittedToken.
        * commit_hw_done() -> CommittedAtomicState
          Revokes access to the AtomicCommitTailObject, and consumes both the
          EnablesCommittedToken and PlaneUpdatesCommitted tokens. This ensures
          that all modesets and plane updates have occurred exactly once.
      * CommittedAtomicState - main object for controlling the atomic_commit_tail
        after the state has been swapped in. This must be returned from the
        atomic_commit_tail function to prove that all of the required commits
        have occurred.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      
      * Currently this solution wouldn't be sufficient for drivers that need
        precise control over the order of each individual modeset or plane
        update. However, this should be very easy to add.
      * Figure out something better for enforcing the plane cleanup then what we
        have right now (e.g. cleaning up planes in the destructor for
        CommittedAtomicState).
      * Add iterator functions that take mutable references to the atomic state
        objects here. This will prevent functions like commit_modeset_disables()
        from being called while a state borrow is taken out, while still allowing
        easy access to the contents of the atomic state at any portion of the
        atomic commit tail.
      * Actually add some macros for generating bitmasks like we do with
        PlaneCommitFlags - right now we just do this by hand.
      49a66dd8
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add VblankSupport · 3e275b69
      Lyude Paul authored
      
      This commit adds bindings for implementing vblank support for a driver's
      CRTCs. These bindings are optional, to account for the fact that not all
      drivers have dedicated hardware vblanks.
      
      In order to accomplish this, we introduce the VblankSupport trait which can
      be implemented on DriverCrtc by drivers which support vblanks. This works
      in the same way as the main Kms trait - drivers which don't support
      hardware vblanks can simply pass PhantomData<Self> to the associated type
      on DriverCrtc. If a driver chooses to implement VblankSupport, VblankImpl
      will be implemented by DRM automatically - and can be passed to the
      VblankImpl associated type on DriverCrtc.
      
      Additionally, we gate methods which only apply to vblank-supporting drivers
      by introducing a VblankDriverCrtc trait that is automatically implemented
      by DRM for CRTC drivers implementing VblankSupport. This works basically in
      the same way as Kms and KmsDriver, but for CRTCs.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      Notes:
      
      * One thing to keep in mind: this trait is implemented on the CRTC as
        opposed to the KMS driver due to the possibility that a driver may have
        multiple different types of CRTCs. As a result, it's not impossible that
        there could potentially be differences in each type's vblank hardware
        implementation. In theory this could lead to a driver mistakenly only
        implementing VblankSupport for some CRTCs and not others, which isn't
        really defined behavior in DRM. As such, one of the dependencies in the
        branch for this patch series preview is a fix to ensure that DRM
        disallows registering drivers that make this mistake.
      
      TODO:
      
      * Technically this patch introduces a soundness issue. We currently allow
        access to a kernel::drm::Device (through UnregisteredKmsDevice's Deref
        implementation) within the kernel::drm::kms::Kms::create_objects trait
        method. A caller could potentially access an uninitialized mutex by
        calling Crtc::vblank_lock() within this context.
        My solution for this is likely going to be adding unregistered variants
        of Crtc and other mode-objects that don't have access to the full set of
        methods on mode objects.
      3e275b69
    • Lyude Paul's avatar
      rust: drm/kms: Add Device::num_crtcs() · 782741a9
      Lyude Paul authored
      
      A binding for checking drm_device.num_crtcs. We'll need this in a moment
      for vblank support, since setting it up requires knowing the number of
      CRTCs that a driver has initialized.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      782741a9
    • Lyude Paul's avatar
      rust: drm: Add Device::event_lock() · f4020258
      Lyude Paul authored
      
      This is just a crate-private helper to use Lock::from_raw() to provide an
      immutable reference to the DRM event_lock, so that it can be used like a
      normal rust spinlock. We'll need this for adding vblank related bindings.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      f4020258
    • Lyude Paul's avatar
      rust: drm/kms: Add DriverCrtc::atomic_enable() and atomic_disable() · 0643ddba
      Lyude Paul authored
      
      Optional trait methods for implementing the atomic_enable and
      atomic_disable callbacks of a CRTC.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      0643ddba
    • Lyude Paul's avatar
      rust: drm/kms: Add DriverCrtc::atomic_begin() and atomic_flush() · 43e348c4
      Lyude Paul authored
      
      Optional trait methods for implementing the atomic_begin and atomic_flush
      callbacks for a CRTC.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      43e348c4
    • Lyude Paul's avatar
      rust: drm/kms: Add RawPlane::framebuffer() · 5c086d84
      Lyude Paul authored
      
      Returns the Framebuffer currently assigned in an atomic plane state.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      5c086d84
    • Lyude Paul's avatar
      rust: drm/kms: Add drm_framebuffer bindings · 93cb2ac8
      Lyude Paul authored
      
      This adds some very simple bindings for drm_framebuffer. We don't use them
      much yet, but we'll eventually be using them when rvkms eventually gets CRC
      and writeback support. Just like Connector objects, these use RcModeObject.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      93cb2ac8
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add RawPlaneState::atomic_helper_check() · a6d9ce69
      Lyude Paul authored
      
      Add a binding for drm_atomic_helper_check_plane_state(). Since we want to
      make sure that the user is passing in the new state for a Crtc instead of
      an old state, we explicitly ask for a reference to a BorrowedCrtcState.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Add support for scaling options
      a6d9ce69
    • Lyude Paul's avatar
      rust: drm/kms: Add RawPlaneState::crtc() · ad61f71e
      Lyude Paul authored
      
      Add a binding for checking drm_plane_state.crtc. Note that we don't have a
      way of knowing what DriverCrtc implementation would be used here (and want
      to make this function also available on OpaquePlaneState types), so we
      return an OpaqueCrtc.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      ad61f71e
    • Lyude Paul's avatar
      rust: drm/kms: Add RawCrtcState::active() · 258500d9
      Lyude Paul authored
      
      A binding for checking drm_crtc_state.active.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      258500d9
    • Lyude Paul's avatar
      rust: drm/kms: Add DriverPlane::atomic_check() · e5f4d3fb
      Lyude Paul authored
      
      Optional trait method for implementing a plane's atomic_check().
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      e5f4d3fb
    • Lyude Paul's avatar
      rust: drm/kms: Add DriverPlane::atomic_update() · a2174ae6
      Lyude Paul authored
      
      A mandatory trait method used for implementing DRM's atomic plane update
      callback.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      a2174ae6
    • Lyude Paul's avatar
      rust: drm/kms: Introduce DriverCrtc::atomic_check() · 15610ea3
      Lyude Paul authored
      
      An optional trait method for implementing a CRTC's atomic state check.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      15610ea3
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add drm_atomic_state bindings · ea59337a
      Lyude Paul authored
      
      Next up is introducing bindings that we can use to represent the global DRM
      atomic state, along with all of the various object states contained within.
      We do this by introducing a few new concepts: borrowed states, atomic state
      mutators, and atomic state composers.
      
      To understand these, we need to quickly touch upon the general life of an
      atomic commit. Assuming a driver does its own internal atomic commit, the
      procedure looks something like this:
      
      * Allocate a new atomic state
      * Duplicate the atomic state of each mode object we want to mutate, and add
        the duplicated state to the new atomic state
      * Check (possibly more then once) the atomic state, possibly modifying it
        along the way
      * Commit the atomic state to software (we'll call this commit time). At
        this point no new objects can be added to the state
      * Finish committing the atomic state to hardware asynchronously
      
      With this in mind, we introduce AtomicStateMutator and AtomicStateComposer
      (along with leaky variants intended for uses in FFI calls). An
      AtomicStateMutator allows mutating an atomic state but does not allow for
      adding new objects to the state. Subsequently, an AtomicStateComposer
      allows for both mutating an atomic state and adding new mode objects. We
      control when we expose each of these types in order to implement the
      limitations required by the aforementioned example.
      
      Note as well that AtomicStateComposer is intended to eventually be usable
      directly by drivers. In this scenario, a driver will be able to create an
      AtomicStateComposer (the equivalent of allocating an atomic state in C) and
      then commit it by passing it to our DRM bindings by-value, insuring that
      once the commit process begins it is impossible to keep using the
      AtomicStateComposer.
      
      The next part of this is allowing users to modify the atomic states of all
      of the objects contained within an atomic state. Since it's an extremely
      common usecase for objects to mutate the atomic state of multiple objects
      at once in an unpredictable order, we need a mechanism that will allow us
      to hand out &mut references to each state while ensuring at runtime that we
      do not break rust's data aliasing rules (which disallow us from ever having
      more then one &mut reference to the same piece of data).
      
      We do this by introducing the concept of a "borrowed" state. This is a very
      similar concept to RefCell, where it is ensured during runtime that when a
      &mut reference is taken out another one cannot be created until the
      corresponding Ref object has been dropped. Our equivalent Ref types are
      BorrowedConnectorState, BorrowedCrtcState, and BorrowedPlaneState.
      
      Each one of these types can be used in the same manner as a Ref - no
      additional borrows for an atomic state may be taken until the existing one
      has been dropped. Subsequently, all of these types implement their
      respective AsRaw* and FromRaw* counter-parts - and allow dereferencing to
      each driver-private data structure for fully qualified borrows (like
      BorrowedCrtcState<'a, CrtcState<T>>. This allows a pretty clean way of
      mutating multiple states at once without ever breaking rust's mutability
      rules.
      
      We'll use all of these types over the next few commits to begin introducing
      various atomic modeset callbacks to each mode object type.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Finish adding state iterators
        We only have one iterator for planes right now, but the plan is to have
        iterators for all types and have two different kind of iterators:
        * State object iterators
          Basically, these just iterate through all of the mode objects of a
          specific type present in an atomic state. Currently this is what our
          plane iterator does.
        * State mutator iterators
          With the existence of AtomicStateMutator and friends, it makes sense to
          have a type of iterator that:
          * Only iterates through unborrowed atomic states, removing the need to
            deal with the Option<> that get_new_*_state() functions return
          * Returns each (object, old_state, new_state) triplet as a dedicated
            type (PlaneUpdate, CrtcUpdate, ConnectorUpdate) that can be upcasted
            from an Opaque type using a single call. This is desirable, as it
            would make iterating through objects with a specific Driver*
            implementation as easy as just adding a .filter_map() call to the
            iterator.
        * Upcast functions for the Borrowed* types
      ea59337a
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add OpaqueEncoder · 0ce1fccf
      Lyude Paul authored
      
      Same thing as OpaquePlane, but for encoders now.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Add upcast functions for this
      0ce1fccf
    • Lyude Paul's avatar
      rust: drm/kms: Add RawPlane and RawPlaneState · 6c64611f
      Lyude Paul authored
      
      Same thing as RawCrtc and RawCrtcState, but for DRM planes now
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      6c64611f
    • Lyude Paul's avatar
      rust: drm/kms: Add RawCrtc and RawCrtcState · 1a422fff
      Lyude Paul authored
      
      Same thing as RawConnector and RawConnectorState, just for CRTCs now.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      1a422fff
    • Lyude Paul's avatar
      rust: drm/kms: Add RawConnector and RawConnectorState · fab5ee81
      Lyude Paul authored
      
      Now that we have more then one way to refer to connectors, we also want to
      ensure that any methods which are common to any kind of connector type can
      be used on all connector representations. This is where RawConnector and
      RawConnectorState come in: we implement these traits for any type which
      implements AsRawConnector or AsRawConnectorState respectively.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      fab5ee81
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add OpaquePlane and OpaquePlaneState · 936228d8
      Lyude Paul authored
      
      Same thing as OpaqueCrtc and OpaqueCrtcState, but for plane states now.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Finish adding upcast functions.
      936228d8
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add OpaqueCrtc and OpaqueCrtcState · 2d60db93
      Lyude Paul authored
      
      This is the same thing as OpaqueConnector and OpaqueConnectorState, but for
      CRTCs now.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Add upcast functions
      2d60db93
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add OpaqueConnector and OpaqueConnectorState · 3f20068c
      Lyude Paul authored
      
      Since we allow drivers to have multiple implementations of DriverConnector
      and DriverConnectorState (in C, the equivalent of this is having multiple
      structs which embed drm_connector) - there are some situations we will run
      into where it's not possible for us to know the corresponding
      DriverConnector or DriverConnectorState for a given connector. The most
      obvious one is iterating through all connectors on a KMS device.
      
      So, take advantage of the various connector traits we added to introduce
      OpaqueConnector<> and OpaqueConnectorState<> which both can be used as a
      DRM connector and connector state respectively without needing to know the
      corresponding traits.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Add upcast functions for these types
      3f20068c
    • Lyude Paul's avatar
      rust: drm/kms: Add ConnectorGuard::set_preferred_mode · cf4eeef4
      Lyude Paul authored
      
      Add a wrapper for `drm_set_preferred_mode()` for our new
      `ConnectorGuard` type so we can set the preferred mode for RVKMS
      connectors.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      cf4eeef4
    • Lyude Paul's avatar
      rust: drm/kms: Add ConnectorGuard::add_modes_noedid() · 7ec49144
      Lyude Paul authored
      
      A simple binding for drm_add_modes_noedid() using the ConnectorGuard type
      we just added.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      7ec49144
    • Lyude Paul's avatar
      rust: drm/kms: Add DriverConnector::get_mode callback · 380657fa
      Lyude Paul authored
      
      Next up is filling out some of the basic connector hotplugging callbacks -
      which we'll need for setting up the fbdev helpers for KMS devices. Note
      that connector hotplugging in DRM follows a BFL scheme: pretty much all
      probing is protected under the mighty drm_device->mode_config.lock, which
      of course is a bit counter-intuitive to rust's locking schemes where data
      is always associated with its lock.
      
      Since that lock is embedded in an FFI type and not a rust type, we need to
      introduce our own wrapper type that acts as a lock acquisition for this.
      This brings us to introducing a few new types:
      
      * ModeConfigGuard - the most basic lock guard, as long as this object is
        alive we are guaranteed to be holding drm_device->mode_config.lock. This
        object doesn't do much else on its own currently.
      * ConnectorGuard - an object which corresponds to a specific typed DRM
        connector. This can only be acquired with a ModeConfigGuard, and will be
        used to allow calling methods that are only safe to call with
        drm_device->mode_config.lock held. Since it implements
        Deref<Target=Connector<T>> as well, it can also be used for any other
        operations that would normally be available on a DRM connector.
      
      And finally, we add the DriverConnector::get_modes() trait method which
      drivers can use to implement the drm_connector_helper_funcs.get_modes
      callback. Note that while we make this trait method mandatory, we only do
      so for the time being since VKMS doesn't do very much with DRM connectors -
      and as such we have no need yet to implement alternative connector probing
      schemes outside of get_modes().
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      380657fa
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add Connector.attach_encoder() · 47e67048
      Lyude Paul authored
      
      This adds a simple binding for completing the last step of creating a DRM
      connector - attaching its encoder. This function should only be called
      before the connector is registered, and DRM should enforce this itself by
      returning an error if a driver tries to add an encoder to an
      already-registered DRM connector.
      
      Note that unlike most of the methods we'll be adding to DRM mode objects,
      this is directly implemented on the Connector<T> type since I don't really
      think it would make sense for us to allow this operation on an
      OpaqueConnector (a DRM connector without a known DriverConnector
      implementation, something we'll be adding in the next few commits).
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Figure out a solution for making sure that this can only be called when a
        Connector is unregistered, probably via an UnregisteredConnector type.
      47e67048
    • Lyude Paul's avatar
      rust: drm/kms: Add bindings for drm_encoder · d143e843
      Lyude Paul authored
      
      The last thing we need to be able to register a KMS driver is the ability
      to create DRM encoders, so let's add bindings for that. Again, these
      bindings follow the same general pattern as CRTCs, planes, and connector
      with one difference: encoders don't have an atomic state.
      
      Note that not having an atomic state doesn't mean there aren't plenty of
      valid usecases for a driver to stick private data within a DRM encoder,
      hence why we reuse the aforementioned pattern.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      d143e843
    • Lyude Paul's avatar
      WIP: rust: drm/kms: Add drm_crtc bindings · 14b4f03a
      Lyude Paul authored
      
      This introduces basic bindings for DRM CRTCs which follow the same general
      pattern as connectors and planes (e.g. AsRawCrtc, AsRawCrtcState, etc.).
      There is one big difference though - drm_crtc_state appears to be the one
      atomic state that actually has data which can be mutated from outside of
      the atomic commit phase - which means we can't keep rust referencs to it,
      and instead need to use the Opaque type and implement things through
      pointers instead.
      
      This should be the last mode object we're introducing for the time being
      with its own atomic state. Note that we've not added bindings for private
      modesetting objects yet, but I don't think those will be needed for rvkms -
      and the same general patterns we're using here should work for adding
      private modesetting objects.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Add commit data in the future
      14b4f03a
    • Lyude Paul's avatar
      rust: drm/kms: Add drm_plane bindings · 71b21d74
      Lyude Paul authored
      
      The next step is adding a set of basic bindings to create a plane, which
      has to happen before we can create a CRTC (since we need to be able to at
      least specify a primary plane for a CRTC upon creation). This mostly
      follows the same general pattern as connectors (AsRawPlane,
      AsRawPlaneState, etc.).
      
      There is one major difference with planes vs. other types of atomic mode
      objects: drm_plane_state isn't the only base plane struct used in DRM
      drivers, as some drivers will use helpers like drm_shadow_plane_state which
      have a drm_plane_state embedded within them.
      
      Since we'll eventually be adding bindings for shadow planes, we introduce a
      PlaneStateHelper trait - which represents any data type which can be used
      as the main wrapping structure around a drm_plane_state - and we implement
      this trait for PlaneState<T>. This trait can be used in our C callbacks to
      allow for drivers to use different wrapping structures without needing to
      implement a separate set of FFI callbacks for each type. Currently planes
      are the only type I'm aware of which do this.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      V2:
      * Start using Gerry Guo's updated #[vtable] function so that our driver
        operations table has a static location in memory
      71b21d74
    • Lyude Paul's avatar
      rust: drm/kms: Add bindings for drm_connector · 18f745d4
      Lyude Paul authored
      
      We start off by introducing wrappers for the first important type of mode
      object: a DRM display connector. This introduces Connector<T:
      DriverConnector> and ConnectorState<T: DriverConnectorState>. Both
      DriverConnector and DriverConnectorState must be implemented by KMS
      drivers, and a driver may have as many implementations of these two traits
      as it needs. This also introduces the general data pattern we'll be using
      for all of the core mode objects that can be used in atomic commits.
      
      It's important to note that both Connector<T> and ConnectorState<T> are
      intended to be "subclassable". To explain what this means, we need to look
      at how a DRM driver normally uses objects like DRM connectors.
      
      Typically, a driver in C will define its connectors like so:
      
      struct foo_connector {
        struct drm_connector base;
        int bar;
      }
      
      Note that we have a drm_connector struct embedded in foo_connector, but we
      have data which comes after it which is defined by the driver. This is
      important for a number of reasons: connectors can have their own mutexes
      and various other hardware-specific information that a driver may want
      access to at any time. The same goes for drm_connector_state, where drivers
      will subclass this struct in the same way. It's worth noting as well that
      it isn't uncommon for a driver to have multiple types of connectors, but
      we'll handle in a later commit.
      
      As a result, we've designed Connector<T> and ConnectorState<T> so that for
      both types: a DRM driver can add custom data into the T. As well, there's
      some basic limitations on how this data may be accessed:
      
      * Data within the `DriverConnector` struct is pinned in order to allow
        mutexes and other structs which need pinning to be stored within it. As
        well, it is impossible to get a direct mutable reference to the data
        within DriverConnector - as there's no locks for doing so which would
        cause a race condition.
      * Data within the `DriverConnectorState` struct is currently not pinned.
        While it's not unheard of for a driver to put something like a mutex in
        its atomic states, (VKMS actually does this in some spots) this quickly
        complicates things especially with nonblocking modesets - and doesn't
        really fit into the philosophy of an atomic state anyway. We may add
        support for this in the future later if this does end up being needed,
        but for now we hold back in order to make it much easier for drivers to
        access private data within the atomic state.
        As well, the functions we provide for converting to/from raw connector
        state pointers are notably different from many other rust types in the
        kernel. Instead of converting raw state pointers to raw ConnectorState<T>
        pointers, we allow for direct immutable and mutable references. The
        reason for this is that it makes accessing private driver data in the
        state much easier, and unlike Connector<T> - we can actually uphold
        all of the required data aliasing rules thanks to states only being
        mutable by a single thread before they've been swapped in.
        Note that currently, we don't provide a way to access said private data
        for ConnectorState<T> since allowing direct access to a &mut
        ConnectorState<T> could allow a caller to modify portions of
        drm_connector_state which are meant to be invariant throughout the
        lifetime of the connector state. We'll address this in the next few
        commits when we introduce the global atomic state type.
      
      And finally - we introduce the following internal traits for the crate side
      of things:
      
        * AsRawConnector - any type which can spit out a *mut
          bindings::drm_connector or be recovered from one
        * AsRawConnectorState - any type which can return a reference to a
          bindings::drm_connector_state
        * private::AsRawConnectorState - just methods for AsRawConnectorState
          that we don't want to be accessible to our users (since they could be
          used to introduce UB)
        * FromRawConnectorState - any type which can be recovered from a raw
          pointer to a bindings::drm_connector_state
      
      The reason for having AsRawConnectorState and FromRawConnectorState as
      separate traits unlike AsRawConnector is due to the fact that we'll
      introduce objects later on which can be used as DRM connector states, but
      cannot be directly derived from a *mut bindings::drm_connector_state
      because they hold additional state or have additional side-effects.
      
      Likewise, we'll also have other objects which can be used as raw DRM
      connectors - hence AsRawConnector.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      18f745d4
    • Lyude Paul's avatar
      rust: drm/kms: Introduce the main ModeConfigObject traits · 70a0ee27
      Lyude Paul authored
      
      The KMS API has a very consistent idea of a "mode config object", which
      includes any object with a drm_mode_object struct embedded in it. These
      objects have their own object IDs which DRM exposes to userspace, and we
      introduce the ModeConfigObject trait to represent any object matching these
      characteristics.
      
      One slightly less consistent trait of these objects however: some mode
      objects have a reference count, while others don't. Since rust requires
      that we are able to define the lifetime of an object up-front, we introduce
      two other super-traits of ModeConfigObject for this:
      
      * StaticModeObject - this trait represents any mode object which does not
        have a reference count of its own. Such objects can be considered to
        share the lifetime of their parent KMS device
      * RcModeObject - this trait represents any mode object which does have its
        own reference count. Objects implementing this trait get a free blanket
        implementation of AlwaysRefCounted, and as such can be used with the ARef
        container without us having to implement AlwaysRefCounted for each
        individual mode object.
      
      This will be able to handle most lifetimes we'll need with one exception:
      it's entirely possible a driver may want to hold a "owned" reference to a
      static mode object. We allow for this by introducing the KmsRef container,
      which grabs an owned refcount to the parent KMS device of a
      StaticModeObject and holds a pointer to said object - essentially allowing
      it to act identically to an owned refcount by preventing the device's
      lifetime from ending until the KmsRef is dropped. I choose not to use
      AlwaysRefCounted for this as holding a refcount to the device has its own
      set of implications since if you forget to drop the KmsRef the device will
      never be destroyed.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      70a0ee27
    • Lyude Paul's avatar
      rust: drm/kms/fbdev: Add FbdevShmem · bf255ed9
      Lyude Paul authored
      
      For drivers which use the shmem based GEM helpers, they'll want to use the
      relevant drm_fbdev_shmem_setup() functions instead of the
      drm_fbdev_dma_setup() functions. To allow for this, introduce another
      FbdevImpl that such drivers can use instead of FbdevDma.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      bf255ed9
    • Lyude Paul's avatar
      WIP: rust: drm: Add traits for registering KMS devices · 1bd59d0b
      Lyude Paul authored
      
      This commit adds some traits for registering DRM devices with KMS support,
      implemented through the kernel::drm::kms::Kms trait. Devices which don't
      have KMS support can simply use PhantomData<Self>.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      
      ---
      
      TODO:
      * Generate feature flags automatically, these shouldn't need to be
        specified by the user
      1bd59d0b
    • Lyude Paul's avatar
      WIP: rust/drm: Add fourcc bindings · 169d51e4
      Lyude Paul authored
      
      This adds some very basic rust bindings for fourcc. We only have a single
      format code added for the moment, but this is enough to get a driver
      registered.
      
      TODO:
      * Write up something to automatically generate constants from the fourcc
        headers
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      169d51e4
    • Lyude Paul's avatar
      WIP: rust: lock: Add B::is_locked() assertion to Guard::new() · f75561b7
      Lyude Paul authored
      TODO: turn this into its own commit in preparation for making Guard::new()
      public
    • Lyude Paul's avatar
      WIP delete me: Fix bug in from_raw() · 6a7f920d
      Lyude Paul authored
      This doesnt' really matter though, since we already decided from_raw() is a
      bad idea when we can just from_raw the actual lock instead
      6a7f920d
    • Lyude Paul's avatar
      rust: lock: Expose Guard::new() and add Guard::new_with() · ca180e8f
      Lyude Paul authored
      
      Since we have the ability to retrieve Lock structures from raw C structures
      now, we also want the ability to do so for guards - as this can be useful
      in the context of C callbacks where we know that a lock is already held,
      and may need to take advantage of that to perform operations under said
      lock.
      
      So, let's make Guard::new() a public function. Additionally, let's also add
      a Guard::new_with() function to match the lock() and lock_with() pattern
      that we currently have with locks. This way users get the additional
      protection of associating the lifetime of the lock context with the Guard
      even in unsafe contexts.
      
      Signed-off-by: Lyude Paul's avatarLyude Paul <lyude@redhat.com>
      ca180e8f
    • Lyude Paul's avatar
      a7b54175
Loading