STRUCT DRM_SCHED_ENTITY(9)

💖 NAME 💖

Okay bestie, welcome to the struct drm_sched_entity(9) page in the Kernel API Manual. This struct is literally a wrapper around a job queue (typically attached to the DRM file_priv). That’s the whole vibe.

---

✨ SYNOPSIS ✨

struct drm_sched_entity {
    struct list_head                list;
    spinlock_t lock;
    struct drm_sched_rq             *rq;
    struct drm_sched_entity_stats   *stats;
    struct drm_gpu_scheduler        **sched_list;
    unsigned int                    num_sched_list;
    enum drm_sched_priority         priority;
    enum drm_sched_priority         rq_priority;
    ktime_t rr_ts;
    struct spsc_queue               job_queue;
    atomic_t fence_seq;
    uint64_t fence_context;
    struct dma_fence                *dependency;
    struct dma_fence_cb             cb;
    atomic_t *guilty;
    struct dma_fence *last_scheduled;
    struct task_struct              *last_user;
    bool stopped;
    struct completion               entity_idle;
    ktime_t oldest_job_waiting;
    struct rb_node                  rb_tree_node;
};

🫶 Members 🫶

• list — Used to append this struct to the list of entities in the runqueue rq under drm_sched_rq.entities.

Protected by drm_sched_rq.lock of rq.

• lock — Lock protecting the run-queue (rq) to which this entity belongs, priority, the list of schedulers (sched_list, num_sched_list) and the rr_ts field.
• rq — Runqueue on which this entity is currently scheduled.

FIXME: Locking is very unclear for this. Writers are protected by lock, but readers are generally lockless and seem to just race with not even a READ_ONCE.

• stats — Stats object reference held by the entity and jobs.
• sched_list — A list of schedulers (struct drm_gpu_scheduler). Jobs from this entity can be scheduled on any scheduler on this list.

This can be modified by calling drm_sched_entity_modify_sched. Locking is entirely up to the driver, see the above function for more details.

This will be set to NULL if num_sched_list equals 1 and rq has been set already.

FIXME: This means priority changes through drm_sched_entity_set_priority will be lost henceforth in this case.

• num_sched_list — Number of drm_gpu_schedulers in the sched_list.
• priority — Priority of the entity. This can be modified by calling drm_sched_entity_set_priority. Protected by lock.
• rq_priority — Run-queue priority.
• rr_ts — Fake timestamp of the last popped job from the entity.
• job_queue — the list of jobs of this entity.
• fence_seq — A linearly increasing seqno incremented with each new drm_sched_fence which is part of the entity.

FIXME: Callers of drm_sched_job_arm need to ensure correct locking, this doesn’t need to be atomic.

• fence_context — A unique context for all the fences which belong to this entity. The drm_sched_fence.scheduled uses the fence_context but drm_sched_fence.finished uses fence_context + 1.
• dependency — The dependency fence of the job which is on the top of the job queue.
• cb — Callback for the dependency fence above.
• guilty — Points to entities’ guilty.
• last_scheduled — Points to the finished fence of the last scheduled job. Only written by drm_sched_entity_pop_job. Can be accessed locklessly from drm_sched_job_arm if the queue is empty.
• last_user — last group leader pushing a job into the entity.
• stopped — Marks the enity as removed from rq and destined for termination. This is set by calling drm_sched_entity_flush.
• entity_idle — Signals when entity is not in use, used to sequence entity cleanup in drm_sched_entity_fini.
• oldest_job_waiting — Marks earliest job waiting in SW queue.
• rb_tree_node — The node used to insert this entity into time based priority queue.

💅 Description 💅

Entities emit jobs in order to their corresponding hardware ring, and the scheduler alternates between entities based on scheduling policy. Periodt. 🔥

🌈 SEE ALSO 🌈

Bestie, go read these too:

• Kernel file ./include/drm/gpu_scheduler.h
• DRM_SCHED_FENCE_DONT_PIPELINE(9)
• DRM_SCHED_FENCE_FLAG_HAS_DEADLINE_BIT(9)
• struct drm_sched_rq(9)
• struct drm_sched_fence(9)
• struct drm_sched_job(9)
• enum drm_gpu_sched_stat(9)
• struct drm_sched_backend_ops(9)
• struct drm_gpu_scheduler(9)
• struct drm_sched_init_args(9)
• struct drm_sched_pending_job_iter(9)
• drm_sched_for_each_pending_job(9)

---

Kernel API Manual, source ./include/drm, October 2026 — page struct drm_sched_entity(9), mwah 💋