STRUCT PANTHOR_VM(9)

okay bestie, welcome to struct panthor_vm(9) from the Kernel API Manual — yes, we're doing kernel struct lore today and it's lowkey iconic 🎀

🎀 NAME 🎀

struct panthor_vm — VM object. That's the name, that's the vibe: virtual memory main character energy ✨

✨ SYNOPSIS ✨

       struct panthor_vm {
           struct drm_gpuvm base;
           struct drm_gpu_scheduler sched;
           struct drm_sched_entity entity;
           struct panthor_device *ptdev;
           u64 memattr;
           struct io_pgtable_ops *pgtbl_ops;
           void *root_page_table;
           struct mutex op_lock;
           struct panthor_vm_op_ctx *op_ctx;
           struct drm_mm mm;
           struct mutex mm_lock;
           struct {
             u64 start;
             u64 end;
           } kernel_auto_va;
           u64 user_va_range;
           struct {
             int id;
             refcount_t active_cnt;
             struct list_head lru_node;
           } as;
           struct {
             struct panthor_heap_pool *pool;
             struct mutex lock;
           } heaps;
           struct list_head node;
           bool for_mcu;
           bool destroyed;
           bool unusable;
           bool unhandled_fault;
           struct {
             u64 start;
             u64 size;
           } locked_region;
           struct {
             struct drm_gem_lru lru;
             struct list_head lru_node;
           } reclaim;
           struct panthor_gem_object *dummy;
        };

🔥 Members 🔥

• base — Inherit from drm_gpuvm. We delegate all the VA management to the common drm_gpuvm framework and only implement hooks to update the MMU page table. delegation slay 💅
• sched — Scheduler used for asynchronous VM_BIND request. We use a 1:1 scheduler here.
• entity — Scheduling entity representing the VM_BIND queue. There's currently one bind queue per VM. It doesn't make sense to allow more given the VM operations are serialized anyway.
• ptdev — Device.
• memattr — Value to program to the AS_MEMATTR register.
• pgtbl_ops — Page table operations.
• root_page_table — Stores the root page table pointer.
• op_lock — Lock used to serialize operations on a VM. The serialization of jobs queued to the VM_BIND queue is already taken care of by drm_sched, but we need to serialize synchronous and asynchronous VM_BIND request. This is what this lock is for.
• op_ctx — The context attached to the currently executing VM operation. NULL when no operation is in progress.
• mm — Memory management object representing the auto-VA/kernel-VA. Used to auto-allocate VA space for kernel-managed objects (tiler heaps, ...). For the MCU VM, this is managing the VA range that's used to map all shared interfaces. For user VMs, the range is specified by userspace, and must not exceed half of the VA space addressable.
• mm_lock — Lock protecting the mm field.
• kernel_auto_va — Automatic VA-range for kernel BOs.
  • kernel_auto_va.start — Start of the automatic VA-range for kernel BOs.
  • kernel_auto_va.end — End of the automatic VA-range for kernel BOs.
• user_va_range — Upper boundary of VAs VM users can map objects against.
• as — Address space related fields.
  • as.id — ID of the address space this VM is bound to. A value of -1 means the VM is inactive/not bound.
  • as.active_cnt — Number of active users of this VM.
  • as.lru_node — Used to insert the VM in panthor_mmu::as::lru_list (the original says “instead” — typo era, but the intent is insert 💀). Active VMs should not be inserted in the LRU list.
• heaps — Tiler heap related fields.
  • heaps.pool — The heap pool attached to this VM. Will stay NULL until someone creates a heap context on this VM.
  • heaps.lock — Lock used to protect access to pool.
• node — Used to insert the VM in panthor_mmu::vm::list.
• for_mcu — True if this is the MCU VM.
• destroyed — True if the VM was destroyed. No further bind requests should be queued to a destroyed VM.
• unusable — True if the VM has turned unusable because something bad happened during an asynchronous request.

We don't try to recover from such failures, because this implies informing userspace about the specific operation that failed, and hoping the userspace driver can replay things from there. This all sounds very complicated for little gain.

Instead, we should just flag the VM as unusable, and fail any further request targeting this VM.

We also provide a way to query a VM state, so userspace can destroy it and create a new one.

As an analogy, this would be mapped to a VK_ERROR_DEVICE_LOST situation, where the logical device needs to be re-created.

• unhandled_fault — Unhandled fault happened. This should be reported to the scheduler, and the queue/group be flagged as faulty as a result.
• locked_region — Information about the currently locked region currently.
  • locked_region.start — Start of the locked region.
  • locked_region.size — Size of the locked region.
• reclaim — Fields related to BO reclaim.
  • reclaim.lru — LRU of BOs that are only mapped to this VM.
  • reclaim.lru_node — Node used to insert the VM in panthor_device::reclaim::vms.
• dummy — Dummy object used for sparse mappings. VM's must keep a reference to the file context-wide dummy BO because they can outlive the file context, which includes the VM pool holding the original dummy BO reference.

🌈 Description 🌈

A VM is an object representing a GPU (or MCU) virtual address space. It embeds the MMU page table for this address space, a tree containing all the virtual mappings of GEM objects, and other things needed to manage the VM.

Except for the MCU VM, which is managed by the kernel, all other VMs are created by userspace and mostly managed by userspace, using the DRM_IOCTL_PANTHOR_VM_BIND ioctl.

A portion of the virtual address space is reserved for kernel objects, like heap chunks, and userspace gets to decide how much of the virtual address space is left to the kernel (half of the virtual address space by default).

👑 SEE ALSO 👑

Kernel file ./drivers/gpu/drm/panthor/panthor_mmu.c — and the whole friend group: struct panthor_as_slot(9), struct panthor_mmu(9), struct panthor_vm_pool(9), struct panthor_vma(9), struct panthor_vm_op_ctx(9), struct panthor_vm_bind_job(9), alloc_pt(9), free_pt(9), panthor_vm_has_unhandled_faults(9), panthor_vm_is_unusable(9), panthor_vm_active(9), panthor_vm_idle(9), panthor_vm_as(9), panthor_vm_alloc_va(9), panthor_vm_free_va(9), panthor_vm_get_bo_for_va(9), panthor_vm_pool_create_vm(9), panthor_vm_pool_destroy_vm(9), panthor_vm_pool_get_vm(9), panthor_vm_pool_destroy(9), panthor_vm_pool_create(9), panthor_mmu_suspend(9), panthor_mmu_resume(9), panthor_mmu_pre_reset(9), panthor_mmu_post_reset(9), panthor_vm_put(9), panthor_vm_get(9), panthor_vm_get_heap_pool(9), panthor_vm_heaps_sizes(9), panthor_vm_resv(9), panthor_vm_bind_job_put(9), panthor_vm_create(9), panthor_vm_bind_job_create(9), panthor_vm_bind_job_prepare_resvs(9), panthor_vm_bind_job_update_resvs(9), panthor_vm_bind_exec_sync_op(9), panthor_vm_map_bo_range(9), panthor_vm_unmap_range(9), panthor_vm_prepare_mapped_bos_resvs(9), panthor_mmu_unplug(9), panthor_mmu_init(9), panthor_mmu_debugfs_init(9), panthor_mmu_pt_cache_init(9), panthor_mmu_pt_cache_fini(9).

---

made with 💖 from ./drivers/gpu/drm/panthor · October 2026 · struct panthor_vm(9) — now go map something responsibly, bestie 🫶