Command Pools

The Vulkan runtime code provides a common VkCommandPool implementation which makes managing the lifetimes of command buffers and recycling their internal state easier. To use the common command pool a driver needs to fill out a vk_command_buffer_ops struct and set the command_buffer_ops field of vk_device.

Warning

doxygenstruct: Cannot find file: /home/user/documentation/docs/mesa/repository/docs/doxygen_xml/index.xml

By reducing the entirety of command buffer lifetime management to these three functions, much of the complexity of command pools can be implemented in common code, providing better, more consistent behavior across Mesa.

Command Buffer Recycling

The common command pool provides automatic command buffer recycling as long as the driver uses the common vkAllocateCommandBuffers() and vkFreeCommandBuffers() implementations. The driver must also provide the reset function pointer in vk_command_buffer_ops.

With the common command buffer pool, when the client calls vkFreeCommandBuffers(), the command buffers are not immediately freed. Instead, they are reset with VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT, their base object is recycled, and they are added to a free list inside the pool. When the client then calls vkAllocateCommandBuffers(), we check the free list and return a recycled command buffer, if any are available. This provides some basic command buffer pooling without the driver doing any additional work.

Custom command pools

If a driver wishes to recycle at a finer granularity than whole command buffers, they can do so by providing their own command pool implementation which wraps vk_command_pool. The common use-case here is if the driver wants to pool command-buffer-internal objects at a finer granularity than whole command buffers. The command pool provides a place where things like GPU command buffers or upload buffers can be cached without having to take a lock.

When implementing a custom command pool, drivers need only implement three entrypoints:

  • vkCreateCommandPool()

  • vkDestroyCommandPool()

  • vkTrimCommandPool()

All of the other entrypoints will be handled by common code so long as the driver’s command pool derives from vk_command_pool.

The driver implementation of the command buffer recycle() function should respect VK_COMMAND_BUFFER_RESET_RELEASE_RESOURCES_BIT and, when set, return any recyclable resources to the command pool. This may be set by the client when it calls vkResetCommandBuffer(), come from a whole-pool reset via VK_COMMAND_POOL_RESET_RELEASE_RESOURCES_BIT, or come from the common command buffer code when a command buffer is recycled.

The driver’s implementation of vkTrimCommandPool() should free any resources that have been cached within the command pool back to the device or back to the OS. It must also call vk_command_pool_trim() to allow the common code to free any recycled command buffers.

Reference

Warning

doxygenstruct: Cannot find file: /home/user/documentation/docs/mesa/repository/docs/doxygen_xml/index.xml

Warning

doxygenfunction: Cannot find file: /home/user/documentation/docs/mesa/repository/docs/doxygen_xml/index.xml

Warning

doxygenfunction: Cannot find file: /home/user/documentation/docs/mesa/repository/docs/doxygen_xml/index.xml

Warning

doxygenfunction: Cannot find file: /home/user/documentation/docs/mesa/repository/docs/doxygen_xml/index.xml