（三） - DRM驱动常用结构体

1，drm_mode_object

对于plane、crtc、encoder、connector几个对象，它们有一个公共基类struct drm_mode_object，这几个对象都由此基类扩展而来（该类作为crtc等结构体的成员）。事实上这个基类扩展出来的子类并不是只有上面提到的几种，只不过这四种比较常见。其定义在include/drm/drm_mode_object.h：

/**
* struct drm_mode_object - base structure for modeset objects
* @id: userspace visible identifier
* @type: type of the object, one of DRM_MODE_OBJECT\_\*
* @properties: properties attached to this object, including values
* @refcount: reference count for objects which with dynamic lifetime
* @free_cb: free function callback, only set for objects with dynamic lifetime
*
* Base structure for modeset objects visible to userspace. Objects can be
* looked up using drm_mode_object_find(). Besides basic uapi interface
* properties like @id and @type it provides two services:
*
* - It tracks attached properties and their values. This is used by &drm_crtc,
*   &drm_plane and &drm_connector. Properties are attached by calling
*   drm_object_attach_property() before the object is visible to userspace.
*
* - For objects with dynamic lifetimes (as indicated by a non-NULL @free_cb) it
*   provides reference counting through drm_mode_object_get() and
*   drm_mode_object_put(). This is used by &drm_framebuffer, &drm_connector
*   and &drm_property_blob. These objects provide specialized reference
*   counting wrappers.
*/
struct drm_mode_object {
   
    uint32_t id;
    uint32_t type;
    struct drm_object_properties *properties;
    struct kref refcount;
    void (*free_cb)(struct kref *kref);
};

包括以下成员：

• id：用户空间可见的唯一标识标识符，基于idr算法分配得到的；
• type：对象的类型，可以是DRM_MODE_OBJECT_*中的一个；
• properties：附加到该对象的属性，包括属性的值；在DRM驱动中，每个对象都可以拥有一组属性（例如分辨率、刷新率等），并且可以动态地增加、删除或修改属性。这些属性可以被用户空间的应用程序或者其他驱动程序获取或者设置；
• refcount：具有动态生命周期的对象的引用计数；指drm_mode_object对象在内核中的生命周期的管理，每个drm_mode_object对象都有一个引用计数；
  * 当一个对象被创建时，它的引用计数被初始化为1；
  * 每当一个新的引用指向该对象时，它的引用计数就会增加1；
  * 每当一个引用被释放时，它的引用计数就会减少1；
  * 当对象的引用计数降为0时，内核会自动释放该对象。
  * 这种方式确保了内核中不会存在不再使用的对象，从而避免了内存泄漏。
  * free_cb：释放函数回调，仅对具有动态生命周期的对象设置；
  该结构体提供了用户空间可见的modeset objects的基本结构，可以通过drm_mode_object_find函数查找对象。

为了更加清晰的了解struct drm_mode_object、struct drm_object_properties、struct drm_property数据结构的关系，我们绘制了如下关系图：

1.1 对象类型

type主要包含以下几种类型，定义在include/uapi/drm/drm_mode.h：

#define DRM_MODE_OBJECT_CRTC 0xcccccccc
#define DRM_MODE_OBJECT_CONNECTOR 0xc0c0c0c0
#define DRM_MODE_OBJECT_ENCODER 0xe0e0e0e0
#define DRM_MODE_OBJECT_MODE 0xdededede
#define DRM_MODE_OBJECT_PROPERTY 0xb0b0b0b0
#define DRM_MODE_OBJECT_FB 0xfbfbfbfb
#define DRM_MODE_OBJECT_BLOB 0xbbbbbbbb
#define DRM_MODE_OBJECT_PLANE 0xeeeeeeee
#define DRM_MODE_OBJECT_ANY 0

1.2 对象属性

struct drm_object_properties用于描述对象的属性，定义在include/drm/drm_mode_object.h：

/**
* struct drm_object_properties - property tracking for &drm_mode_object
*/
struct drm_object_properties {
   
    /**
     * @count: number of valid properties, must be less than or equal to
     * DRM_OBJECT_MAX_PROPERTY.
     */

    int count;
    /**
     * @properties: Array of pointers to &drm_property.
     *
     * NOTE: if we ever start dynamically destroying properties (ie.
     * not at drm_mode_config_cleanup() time), then we'd have to do
     * a better job of detaching property from mode objects to avoid
     * dangling property pointers:
     */
    struct drm_property *properties[DRM_OBJECT_MAX_PROPERTY];

    /**
     * @values: Array to store the property values, matching @properties. Do
     * not read/write values directly, but use
     * drm_object_property_get_value() and drm_object_property_set_value().
     *
     * Note that atomic drivers do not store mutable properties in this
     * array, but only the decoded values in the corresponding state
     * structure. The decoding is done using the &drm_crtc.atomic_get_property and
     * &drm_crtc.atomic_set_property hooks for &struct drm_crtc. For
     * &struct drm_plane the hooks are &drm_plane_funcs.atomic_get_property and
     * &drm_plane_funcs.atomic_set_property. And for &struct drm_connector
     * the hooks are &drm_connector_funcs.atomic_get_property and
     * &drm_connector_funcs.atomic_set_property .
     *
     * Hence atomic drivers should not use drm_object_property_set_value()
     * and drm_object_property_get_value() on mutable objects, i.e. those
     * without the DRM_MODE_PROP_IMMUTABLE flag set.
     *
     * For atomic drivers the default value of properties is stored in this
     * array, so drm_object_property_get_default_value can be used to
     * retrieve it.
     */
    uint64_t values[DRM_OBJECT_MAX_PROPERTY];
};

该结构体包含以下字段：

• count：properties数组长度，必须小于或等于DRM_OBJECT_MAX_PROPERTY（值为24）；
• properties：指向drm_property的指针数组；
• values：用于存储属性值的数组，与properties匹配；

其中struct drm_property定义在include/drm/drm_property.h:

/**
* struct drm_property - modeset object property
*
* This structure represent a modeset object property. It combines both the name
* of the property with the set of permissible values. This means that when a
* driver wants to use a property with the same name on different objects, but
* with different value ranges, then it must create property for each one. An
* example would be rotation of &drm_plane, when e.g. the primary plane cannot
* be rotated. But if both the name and the value range match, then the same
* property structure can be instantiated multiple times for the same object.
* Userspace must be able to cope with this and cannot assume that the same
* symbolic property will have the same modeset object ID on all modeset
* objects.
*
* Properties are created by one of the special functions, as explained in
* detail in the @flags structure member.
*
* To actually expose a property it must be attached to each object using
* drm_object_attach_property(). Currently properties can only be attached to
* &drm_connector, &drm_crtc and &drm_plane.
*
* Properties are also used as the generic metadatatransport for the atomic
* IOCTL. Everything that was set directly in structures in the legacy modeset
* IOCTLs (like the plane source or destination windows, or e.g. the links to
* the CRTC) is exposed as a property with the DRM_MODE_PROP_ATOMIC flag set.
*/
struct drm_property {
   
    /**
     * @head: per-device list of properties, for cleanup.
     */
    struct list_head head;

    /**
     * @base: base KMS object
     */
    struct drm_mode_object base;

    /**
     * @flags:
     *
     * Property flags and type. A property needs to be one of the following
     * types:
     *
     * DRM_MODE_PROP_RANGE
     *     Range properties report their minimum and maximum admissible unsigned values.
     *     The KMS core verifies that values set by application fit in that
     *     range. The range is unsigned. Range properties are created using
     *     drm_property_create_range().
     *
     * DRM_MODE_PROP_SIGNED_RANGE
     *     Range properties report their minimum and maximum admissible unsigned values.
     *     The KMS core verifies that values set by application fit in that
     *     range. The range is signed. Range properties are created using
     *     drm_property_create_signed_range().
     *
     * DRM_MODE_PROP_ENUM
     *     Enumerated properties take a numerical value that ranges from 0 to
     *     the number of enumerated values defined by the property minus one,
     *     and associate a free-formed string name to each value. Applications
     *     can retrieve the list of defined value-name pairs and use the
     *     numerical value to get and set property instance values. Enum
     *     properties are created using drm_property_create_enum().
     *
     * DRM_MODE_PROP_BITMASK
     *     Bitmask properties are enumeration properties that additionally
     *     restrict all enumerated values to the 0..63 range. Bitmask property
     *     instance values combine one or more of the enumerated bits defined
     *     by the property. Bitmask properties are created using
     *     drm_property_create_bitmask().
     *
     * DRM_MODE_PROP_OBJECT
     *     Object properties are used to link modeset objects. This is used
     *     extensively in the atomic support to create the display pipeline,
     *     by linking &drm_framebuffer to &drm_plane, &drm_plane to
     *     &drm_crtc and &drm_connector to &drm_crtc. An object property can
     *     only link to a specific type of &drm_mode_object, this limit is
     *     enforced by the core. Object properties are created using
     *     drm_property_create_object().
     *
     *     Object properties work like blob properties, but in a more
     *     general fashion. They are limited to atomic drivers and must have
     *     the DRM_MODE_PROP_ATOMIC flag set.
     *
     * DRM_MODE_PROP_BLOB
     *     Blob properties store a binary blob without any format restriction.
     *     The binary blobs are created as KMS standalone objects, and blob
     *     property instance values store the ID of their associated blob
     *     object. Blob properties are created by calling
     *     drm_property_create() with DRM_MODE_PROP_BLOB as the type.
     *
     *     Actual blob objects to contain blob data are created using
     *     drm_property_create_blob(), or through the corresponding IOCTL.
     *
     *     Besides the built-in limit to only accept blob objects blob
     *     properties work exactly like object properties. The only reasons
     *     blob properties exist is backwards compatibility with existing
     *     userspace.
     *
     * In addition a property can have any combination of the below flags:
     *
     * DRM_MODE_PROP_ATOMIC
     *     Set for properties which encode atomic modeset state. Such
     *     properties are not exposed to legacy userspace.
     *
     * DRM_MODE_PROP_IMMUTABLE
     *     Set for properties whose values cannot be changed by
     *     userspace. The kernel is allowed to update the value of these
     *     properties. This is generally used to expose probe state to
     *     userspace, e.g. the EDID, or the connector path property on DP
     *     MST sinks. Kernel can update the value of an immutable property
     *     by calling drm_object_property_set_value().
     */
    uint32_t flags;

    /**
     * @name: symbolic name of the properties
     */
    char name[DRM_PROP_NAME_LEN];

    /**
     * @num_values: size of the @values array.
     */
    uint32_t num_values;

    /**
     * @values:
     *
     * Array with limits and values for the property. The
     * interpretation of these limits is dependent upon the type per @flags.
     */
    uint64_t *values;

    /**
     * @dev: DRM device
     */
    struct drm_device *dev;

    /**
     * @enum_list:
     *
     * List of &drm_prop_enum_list structures with the symbolic names for
     * enum and bitmask values.
     */
    struct list_head enum_list;
};

2，drm_framebuffer

struct drm_framebuffer表示一个提供给CRTC的抽象内存对象。

/**
* struct drm_framebuffer - frame buffer object
*
* Note that the fb is refcounted for the benefit of driver internals,
* for example some hw, disabling a CRTC/plane is asynchronous, and
* scanout does not actually complete until the next vblank.  So some
* cleanup (like releasing the reference(s) on the backing GEM bo(s))
* should be deferred.  In cases like this, the driver would like to
* hold a ref to the fb even though it has already been removed from
* userspace perspective. See drm_framebuffer_get() and
* drm_framebuffer_put().
*
* The refcount is stored inside the mode object @base.
*/
struct drm_framebuffer {
   
    /**
     * @dev: DRM device this framebuffer belongs to
     */
    struct drm_device *dev;
    /**
     * @head: Place on the &drm_mode_config.fb_list, access protected by
     * &drm_mode_config.fb_lock.
     */
    struct list_head head;

    /**
     * @base: base modeset object structure, contains the reference count.
     */
    struct drm_mode_object base;

    /**
     * @comm: Name of the process allocating the fb, used for fb dumping.
     */
    char comm[TASK_COMM_LEN];

    /**
     * @format: framebuffer format information
     */
    const struct drm_format_info *format;
    /**
     * @funcs: framebuffer vfunc table
     */
    const struct drm_framebuffer_funcs *funcs;
    /**
     * @pitches: Line stride per buffer. For userspace created object this
     * is copied from drm_mode_fb_cmd2.
     */
    unsigned int pitches[DRM_FORMAT_MAX_PLANES];
    /**
     * @offsets: Offset from buffer start to the actual pixel data in bytes,
     * per buffer. For userspace created object this is copied from
     * drm_mode_fb_cmd2.
     *
     * Note that this is a linear offset and does not take into account
     * tiling or buffer layout per @modifier. It is meant to be used when
     * the actual pixel data for this framebuffer plane starts at an offset,
     * e.g. when multiple planes are allocated within the same backing
     * storage buffer object. For tiled layouts this generally means its
     * @offsets must at least be tile-size aligned, but hardware often has
     * stricter requirements.
     *
     * This should not be used to specifiy x/y pixel offsets into the buffer
     * data (even for linear buffers). Specifying an x/y pixel offset is
     * instead done through the source rectangle in &struct drm_plane_state.
     */
    unsigned int offsets[DRM_FORMAT_MAX_PLANES];
    /**
     * @modifier: Data layout modifier. This is used to describe
     * tiling, or also special layouts (like compression) of auxiliary
     * buffers. For userspace created object this is copied from
     * drm_mode_fb_cmd2.
     */
    uint64_t modifier;
    /**
     * @width: Logical width of the visible area of the framebuffer, in
     * pixels.
     */
    unsigned int width;
    /**
     * @height: Logical height of the visible area of the framebuffer, in
     * pixels.
     */
    unsigned int height;
    /**
     * @flags: Framebuffer flags like DRM_MODE_FB_INTERLACED or
     * DRM_MODE_FB_MODIFIERS.
     */
    int flags;
    /**
     * @hot_x: X coordinate of the cursor hotspot. Used by the legacy cursor
     * IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR
     * universal plane.
     */
    int hot_x;
    /**
     * @hot_y: Y coordinate of the cursor hotspot. Used by the legacy cursor
     * IOCTL when the driver supports cursor through a DRM_PLANE_TYPE_CURSOR
     * universal plane.
     */
    int hot_y;
    /**
     * @filp_head: Placed on &drm_file.fbs, protected by &drm_file.fbs_lock.
     */
    struct list_head filp_head;
    /**
     * @obj: GEM objects backing the framebuffer, one per plane (optional).
     *
     * This is used by the GEM framebuffer helpers, see e.g.
     * drm_gem_fb_create().
     */
    struct drm_gem_object *obj[DRM_FORMAT_MAX_PLANES];
};

struct drm_framebuffer 主要元素的展示如下图所示(来自brezillon-drm-kms)，内存缓冲区组织，采取FOURCC格式代码：

3，struct drm_device

linux内核使用struct drm_device数据结构来描述一个drm设备，定义在include/drm/drm_device.h：

/**
* struct drm_device - DRM device structure
*
* This structure represent a complete card that
* may contain multiple heads.
*/
struct drm_device {
   
    /** @if_version: Highest interface version set */
    int if_version;

    /** @ref: Object ref-count */
    struct kref ref;

    /** @dev: Device structure of bus-device */
    struct device *dev;

    /**
     * @managed:
     *
     * Managed resources linked to the lifetime of this &drm_device as
     * tracked by @ref.
     */
    struct {
   
        /** @managed.resources: managed resources list */
        struct list_head resources;
        /** @managed.final_kfree: pointer for final kfree() call */
        void *final_kfree;
        /** @managed.lock: protects @managed.resources */
        spinlock_t lock;
    } managed;

    /** @driver: DRM driver managing the device */
    const struct drm_driver *driver;

    /**
     * @dev_private:
     *
     * DRM driver private data. This is deprecated and should be left set to
     * NULL.
     *
     * Instead of using this pointer it is recommended that drivers use
     * devm_drm_dev_alloc() and embed struct &drm_device in their larger
     * per-device structure.
     */
    void *dev_private;

    /** @primary: Primary node */
    struct drm_minor *primary;

    /** @render: Render node */
    struct drm_minor *render;

    /**
     * @registered:
     *
     * Internally used by drm_dev_register() and drm_connector_register().
     */
    bool registered;

    /**
     * @master:
     *
     * Currently active master for this device.
     * Protected by &master_mutex
     */
    struct drm_master *master;

    /**
     * @driver_features: per-device driver features
     *
     * Drivers can clear specific flags here to disallow
     * certain features on a per-device basis while still
     * sharing a single &struct drm_driver instance across
     * all devices.
     */
    u32 driver_features;

    /**
     * @unplugged:
     *
     * Flag to tell if the device has been unplugged.
     * See drm_dev_enter() and drm_dev_is_unplugged().
     */
    bool unplugged;

    /** @anon_inode: inode for private address-space */
    struct inode *anon_inode;

    /** @unique: Unique name of the device */
    char *unique;

    /**
     * @struct_mutex:
     *
     * Lock for others (not &drm_minor.master and &drm_file.is_master)
     *
     * WARNING:
     * Only drivers annotated with DRIVER_LEGACY should be using this.
     */
    struct mutex struct_mutex;

    /**
     * @master_mutex:
     *
     * Lock for &drm_minor.master and &drm_file.is_master
     */
    struct mutex master_mutex;

    /**
     * @open_count:
     *
     * Usage counter for outstanding files open,
     * protected by drm_global_mutex
     */
    atomic_t open_count;

    /** @filelist_mutex: Protects @filelist. */
    struct mutex filelist_mutex;
    /**
     * @filelist:
     *
     * List of userspace clients, linked through &drm_file.lhead.
     */
    struct list_head filelist;

    /**
     * @filelist_internal:
     *
     * List of open DRM files for in-kernel clients.
     * Protected by &filelist_mutex.
     */
    struct list_head filelist_internal;

    /**
     * @clientlist_mutex:
     *
     * Protects &clientlist access.
     */
    struct mutex clientlist_mutex;

    /**
     * @clientlist:
     *
     * List of in-kernel clients. Protected by &clientlist_mutex.
     */
    struct list_head clientlist;

    /**
     * @vblank_disable_immediate:
     *
     * If true, vblank interrupt will be disabled immediately when the
     * refcount drops to zero, as opposed to via the vblank disable
     * timer.
     *
     * This can be set to true it the hardware has a working vblank counter
     * with high-precision timestamping (otherwise there are races) and the
     * driver uses drm_crtc_vblank_on() and drm_crtc_vblank_off()
     * appropriately. See also @max_vblank_count and
     * &drm_crtc_funcs.get_vblank_counter.
     */
    bool vblank_disable_immediate;

    /**
     * @vblank:
     *
     * Array of vblank tracking structures, one per &struct drm_crtc. For
     * historical reasons (vblank support predates kernel modesetting) this
     * is free-standing and not part of &struct drm_crtc itself. It must be
     * initialized explicitly by calling drm_vblank_init().
     */
    struct drm_vblank_crtc *vblank;

    /**
     * @vblank_time_lock:
     *
     *  Protects vblank count and time updates during vblank enable/disable
     */
    spinlock_t vblank_time_lock;
    /**
     * @vbl_lock: Top-level vblank references lock, wraps the low-level
     * @vblank_time_lock.
     */
    spinlock_t vbl_lock;

    /**
     * @max_vblank_count:
     *
     * Maximum value of the vblank registers. This value +1 will result in a
     * wrap-around of the vblank register. It is used by the vblank core to
     * handle wrap-arounds.
     *
     * If set to zero the vblank core will try to guess the elapsed vblanks
     * between times when the vblank interrupt is disabled through
     * high-precision timestamps. That approach is suffering from small
     * races and imprecision over longer time periods, hence exposing a
     * hardware vblank counter is always recommended.
     *
     * This is the statically configured device wide maximum. The driver
     * can instead choose to use a runtime configurable per-crtc value
     * &drm_vblank_crtc.max_vblank_count, in which case @max_vblank_count
     * must be left at zero. See drm_crtc_set_max_vblank_count() on how
     * to use the per-crtc value.
     *
     * If non-zero, &drm_crtc_funcs.get_vblank_counter must be set.
     */
    u32 max_vblank_count;

    /** @vblank_event_list: List of vblank events */
    struct list_head vblank_event_list;

    /**
     * @event_lock:
     *
     * Protects @vblank_event_list and event delivery in
     * general. See drm_send_event() and drm_send_event_locked().
     */
    spinlock_t event_lock;

    /** @num_crtcs: Number of CRTCs on this device */
    unsigned int num_crtcs;

    /** @mode_config: Current mode config */
    struct drm_mode_config mode_config;

    /** @object_name_lock: GEM information */
    struct mutex object_name_lock;

    /** @object_name_idr: GEM information */
    struct idr object_name_idr;

    /** @vma_offset_manager: GEM information */
    struct drm_vma_offset_manager *vma_offset_manager;

    /** @vram_mm: VRAM MM memory manager */
    struct drm_vram_mm *vram_mm;

    /**
     * @switch_power_state:
     *
     * Power state of the client.
     * Used by drivers supporting the switcheroo driver.
     * The state is maintained in the
     * &vga_switcheroo_client_ops.set_gpu_state callback
     */
    enum switch_power_state switch_power_state;

    /**
     * @fb_helper:
     *
     * Pointer to the fbdev emulation structure.
     * Set by drm_fb_helper_init() and cleared by drm_fb_helper_fini().
     */
    struct drm_fb_helper *fb_helper;

    /* Everything below here is for legacy driver, never use! */
    /* private: */
#if IS_ENABLED(CONFIG_DRM_LEGACY)
    /* List of devices per driver for stealth attach cleanup */
    struct list_head legacy_dev_list;

#ifdef __alpha__
    /** @hose: PCI hose, only used on ALPHA platforms. */
    struct pci_controller *hose;
#endif

    /* AGP data */
    struct drm_agp_head *agp;

    /* Context handle management - linked list of context handles */
    struct list_head ctxlist;

    /* Context handle management - mutex for &ctxlist */
    struct mutex ctxlist_mutex;

    /* Context handle management */
    struct idr ctx_idr;

    /* Memory management - linked list of regions */
    struct list_head maplist;

    /* Memory management - user token hash table for maps */
    struct drm_open_hash map_hash;

    /* Context handle management - list of vmas (for