SPLIT AND MERGE(9)

💖 Split and Merge 💖

okay bestie, this is Split and Merge, section 9 of the Kernel API Manual, and it's giving “GPU VA manager does mapping algebra” in the most iconic way. ✨

Besides its capability to manage and represent a GPU VA space, the GPU VA manager also provides functions to let drm_gpuvm calculate a sequence of operations to satisfy a given map or unmap request. No cap.

So the DRM GPU VA manager provides an algorithm implementing splitting and merging of existing GPU VA mappings with the ones that are requested to be mapped or unmapped. This feature is required by the Vulkan API to implement Vulkan 'Sparse Memory Bindings' — drivers' UAPIs often refer to this as VM BIND. 🫶

Drivers can call drm_gpuvm_sm_map to receive a sequence of callbacks containing map, unmap and remap operations for a given newly requested mapping. That sequence of callbacks represents the set of operations to execute in order to integrate the new mapping cleanly into the current state of the GPU VA space. 💅

Depending on how the new GPU VA mapping intersects with the existing mappings of the GPU VA space, the drm_gpuvm_ops callbacks contain an arbitrary amount of unmap operations, a maximum of two remap operations and a single map operation. The caller might receive no callback at all if no operation is required, e.g. if the requested mapping already exists in the exact same way. iconic no-op behavior, fr fr.

The single map operation represents the original map operation requested by the caller.

drm_gpuva_op_unmap contains a 'keep' field, which indicates whether the drm_gpuva to unmap is physically contiguous with the original mapping request. Optionally, if 'keep' is set, drivers may keep the actual page table entries for this drm_gpuva, adding the missing page table entries only and update the drm_gpuvm's view of things accordingly. 🎀

Drivers may do the same optimization, namely delta page table updates, also for remap operations. This is possible since drm_gpuva_op_remap consists of one unmap operation and one or two map operations, such that drivers can derive the page table update delta accordingly.

Note that there can't be more than two existing mappings to split up — one at the beginning and one at the end of the new mapping — hence there is a maximum of two remap operations. 📌

Analogous to drm_gpuvm_sm_map, drm_gpuvm_sm_unmap uses drm_gpuvm_ops to call back into the driver in order to unmap a range of GPU VA space. The logic behind this function is way simpler though: for all existing mappings enclosed by the given range, unmap operations are created. For mappings which are only partially located within the given range, remap operations are created such that those mappings are split up and re-mapped partially. 🦋

As an alternative to drm_gpuvm_sm_map and drm_gpuvm_sm_unmap, drm_gpuvm_sm_map_ops_create and drm_gpuvm_sm_unmap_ops_create can be used to directly obtain an instance of struct drm_gpuva_ops containing a list of drm_gpuva_op, which can be iterated with drm_gpuva_for_each_op. This list contains the drm_gpuva_ops analogous to the callbacks one would receive when calling drm_gpuvm_sm_map or drm_gpuvm_sm_unmap. While this way requires more memory (to allocate the drm_gpuva_ops), it provides drivers a way to iterate the drm_gpuva_op multiple times, e.g. once in a context where memory allocations are possible (e.g. to allocate GPU page tables) and once in the dma-fence signalling critical path. ✨

To update the drm_gpuvm's view of the GPU VA space, drm_gpuva_insert and drm_gpuva_remove may be used. These functions can safely be used from drm_gpuvm_ops callbacks originating from drm_gpuvm_sm_map or drm_gpuvm_sm_unmap. However, it might be more convenient to use the provided helper functions drm_gpuva_map, drm_gpuva_remap and drm_gpuva_unmap instead. 💖

The following diagram depicts the basic relationships of existing GPU VA mappings, a newly requested mapping and the resulting mappings as implemented by drm_gpuvm_sm_map — it doesn't cover any arbitrary combinations of these. It's a little art gallery of mapping glow-ups, ngl. 🖼️✨

1. Requested mapping is identical — replace it, but indicate the backing PTEs could be kept 🎀

          :

                 0     a     1
            old: |-----------| (bo_offset=n)

                 0     a     1
            req: |-----------| (bo_offset=n)

                 0     a     1
            new: |-----------| (bo_offset=n)

2. Requested mapping is identical, except for the BO offset — hence replace the mapping 💫

          :

                 0     a     1
            old: |-----------| (bo_offset=n)

                 0     a     1
            req: |-----------| (bo_offset=m)

                 0     a     1
            new: |-----------| (bo_offset=m)

3. Requested mapping is identical, except for the backing BO — hence replace the mapping 🦋

          :

                 0     a     1
            old: |-----------| (bo_offset=n)

                 0     b     1
            req: |-----------| (bo_offset=n)

                 0     b     1
            new: |-----------| (bo_offset=n)

4. Existent mapping is a left aligned subset of the requested one — hence replace the existing one 🌸

          :

                 0  a  1
            old: |-----|       (bo_offset=n)

                 0     a     2
            req: |-----------| (bo_offset=n)

                 0     a     2
            new: |-----------| (bo_offset=n)

note: We expect to see the same result for a request with a different BO and/or non-contiguous BO offset. 😌

5. Requested mapping's range is a left aligned subset of the existing one, but backed by a different BO — hence map the requested mapping and split the existing one, adjusting its BO offset 💅

          :

                 0     a     2
            old: |-----------| (bo_offset=n)

                 0  b  1
            req: |-----|       (bo_offset=n)

                 0  b  1  a' 2
            new: |-----|-----| (b.bo_offset=n, a.bo_offset=n+1)

note: We expect to see the same result for a request with a different BO and/or non-contiguous BO offset. 😌

6. Existent mapping is a superset of the requested mapping — split it up, but indicate that the backing PTEs could be kept ✨

          :

                 0     a     2
            old: |-----------| (bo_offset=n)

                 0  a  1
            req: |-----|       (bo_offset=n)

                 0  a  1  a' 2
            new: |-----|-----| (a.bo_offset=n, a'.bo_offset=n+1)

7. Requested mapping's range is a right aligned subset of the existing one, but backed by a different BO — hence map the requested mapping and split the existing one, without adjusting the BO offset 💖

          :

                 0     a     2
            old: |-----------| (bo_offset=n)

                       1  b  2
            req:       |-----| (bo_offset=m)

                 0  a  1  b  2
            new: |-----|-----| (a.bo_offset=n,b.bo_offset=m)

8. Existent mapping is a superset of the requested mapping — split it up, but indicate that the backing PTEs could be kept 🫶

          :

                  0     a     2
            old: |-----------| (bo_offset=n)

                       1  a  2
            req:       |-----| (bo_offset=n+1)

                 0  a' 1  a  2
            new: |-----|-----| (a'.bo_offset=n, a.bo_offset=n+1)

9. Existent mapping is overlapped at the end by the requested mapping backed by a different BO — hence map the requested mapping and split up the existing one, without adjusting the BO offset 🔥

          :

                 0     a     2
            old: |-----------|       (bo_offset=n)

                       1     b     3
            req:       |-----------| (bo_offset=m)

                 0  a  1     b     3
            new: |-----|-----------| (a.bo_offset=n,b.bo_offset=m)

10. Existent mapping is overlapped by the requested mapping, both having the same backing BO with a contiguous offset — indicate the backing PTEs of the old mapping could be kept 👑

           :

                  0     a     2
             old: |-----------|       (bo_offset=n)

                        1     a     3
             req:       |-----------| (bo_offset=n+1)

                  0  a' 1     a     3
             new: |-----|-----------| (a'.bo_offset=n, a.bo_offset=n+1)

11. Requested mapping's range is a centered subset of the existing one having a different backing BO — hence map the requested mapping and split up the existing one in two mappings, adjusting the BO offset of the right one accordingly 🧚

           :

                  0        a        3
             old: |-----------------| (bo_offset=n)

                        1  b  2
             req:       |-----|       (bo_offset=m)

                  0  a  1  b  2  a' 3
             new: |-----|-----|-----| (a.bo_offset=n,b.bo_offset=m,a'.bo_offset=n+2)

12. Requested mapping is a contiguous subset of the existing one — split it up, but indicate that the backing PTEs could be kept 🌈

           :

                  0        a        3
             old: |-----------------| (bo_offset=n)

                        1  a  2
             req:       |-----|       (bo_offset=n+1)

                  0  a' 1  a  2 a'' 3
             old: |-----|-----|-----| (a'.bo_offset=n, a.bo_offset=n+1, a''.bo_offset=n+2)

13. Existent mapping is a right aligned subset of the requested one — hence replace the existing one ⭐

           :

                        1  a  2
             old:       |-----| (bo_offset=n+1)

                  0     a     2
             req: |-----------| (bo_offset=n)

                  0     a     2
             new: |-----------| (bo_offset=n)

note: We expect to see the same result for a request with a different bo and/or non-contiguous bo_offset. 💅

14. Existent mapping is a centered subset of the requested one — hence replace the existing one 💜

           :

                        1  a  2
             old:       |-----| (bo_offset=n+1)

                  0        a       3
             req: |----------------| (bo_offset=n)

                  0        a       3
             new: |----------------| (bo_offset=n)

note: We expect to see the same result for a request with a different bo and/or non-contiguous bo_offset. 💅

15. Existent mappings is overlapped at the beginning by the requested mapping backed by a different BO — hence map the requested mapping and split up the existing one, adjusting its BO offset accordingly 🍓

           :

                        1     a     3
             old:       |-----------| (bo_offset=n)

                  0     b     2
             req: |-----------|       (bo_offset=m)

                  0     b     2  a' 3
             new: |-----------|-----| (b.bo_offset=m,a.bo_offset=n+2)

✨ SEE ALSO ✨

okay so like, this is the part where I hand you the whole friend group 😌 every single one of these is somebody you're gonna want in your contacts, no cap. Start with the actual source file and the big-picture pages, then we get into the individual besties.

• ./drivers/gpu/drm/drm_gpuvm.c — the kernel file, the mothership, the main character herself 💅
• Overview(9) — the vibe-setting origin story, read this first fr
• Madvise Logic - Splitting and Traversal(9) — literally the whole reason this page exists
• Locking(9) — the rules about who gets to touch what and when, please respect them 🙏
• Examples(9) — actual working code instead of me just telling you things

---

🧚 the vm_bo list helpers (the little goblins)

• get_next_vm_bo_from_list(9)
• for_each_vm_bo_in_list(9)
• restore_vm_bo_list(9)

🧟 bo lifecycle & zombie behaviour

• drm_gpuvm_bo_is_zombie(9) — yes, things here can be undead, and yes, you have to check
• drm_gpuvm_bo_list_add(9)
• drm_gpuvm_bo_list_del_init(9)
• drm_gpuvm_bo_list_del(9)

🩷 range + reservation setup

• drm_gpuvm_range_valid(9)
• drm_gpuvm_resv_object_alloc(9)
• drm_gpuvm_init(9) — the birth certificate
• drm_gpuvm_put(9) — the goodbye, pls do it properly

🔐 prepare & lock era

• drm_gpuvm_prepare_vm(9)
• drm_gpuvm_prepare_objects(9)
• drm_gpuvm_prepare_range(9)
• drm_gpuvm_exec_lock(9)
• drm_gpuvm_exec_lock_array(9)
• drm_gpuvm_exec_lock_range(9)

✅ validate & fences

• drm_gpuvm_validate(9) — vibe check for your buffers, basically
• drm_gpuvm_resv_add_fence(9)

🦋 the bo grab-bag (create / put / find)

• drm_gpuvm_bo_create(9)
• drm_gpuvm_bo_put(9)
• drm_gpuvm_bo_put_deferred(9)
• drm_gpuvm_bo_deferred_cleanup(9)
• drm_gpuvm_bo_find(9)
• drm_gpuvm_bo_obtain_locked(9)
• drm_gpuvm_bo_obtain_prealloc(9)
• drm_gpuvm_bo_extobj_add(9)
• drm_gpuvm_bo_evict(9)

🌸 raw gpuva operations (no thoughts, just insert and remove)

• drm_gpuva_insert(9)
• drm_gpuva_remove(9)
• drm_gpuva_link(9)
• drm_gpuva_unlink(9)
• drm_gpuva_unlink_defer(9)

🔎 finding things + empty intervals

• drm_gpuva_find_first(9)
• drm_gpuva_find(9)
• drm_gpuvm_interval_empty(9)

🎀 map / remap / unmap trio

• drm_gpuva_map(9)
• drm_gpuva_remap(9)
• drm_gpuva_unmap(9)

👑 split & merge, the actual headline acts

• drm_gpuvm_sm_map(9)
• drm_gpuvm_sm_unmap(9)
• drm_gpuvm_sm_map_exec_lock(9)
• drm_gpuvm_sm_unmap_exec_lock(9)

🫶 ops create / free squad

• drm_gpuvm_sm_map_ops_create(9)
• drm_gpuvm_madvise_ops_create(9)
• drm_gpuvm_sm_unmap_ops_create(9)
• drm_gpuvm_prefetch_ops_create(9)
• drm_gpuvm_bo_unmap_ops_create(9)
• drm_gpuva_ops_free(9) — always clean up, I'm begging 😭

---

bestie that's 49 functions plus the kernel file and four overview pages. if you only remember one thing: read Overview(9) before you go poking at anything in here, okay? iykyk 💖

---

and that's a wrap on part 2!! 🎀 this whole thing lives under the source path ./drivers/gpu/drm, dated October 2026, and it's the Split and Merge(9) manual page — go forth and merge responsibly, my love ✨🦋👑