libwsbm

libwsbm

Purpose and background

The libwsbm (wsbm stands for Window System Buffer Manager) library previously lived as a dri buffer manager within mesa. Subsequently that buffer manager was stripped, rewritten completely and put in libdrm. The libwsbm library is a variant that is closer to the original, supports buffer pools and fence pools for various use cases and, above all, is designed for multithreaded clients and thus has a clear distinction between context-specific structures that needs no locking, and shared structures that

  1. Need mutex protection
  2. Must not contain any context specific data, for example relocation information.

Libwsbm do contain buffer pool backends that interface to drm/ttm user-space interfaces, but since libwsbm can be used without drm it's not a drm user-space interface. Therefore it currently lives outside libdrm.

Buffer pools

The libwsbm library allows pluggable buffer pools. These pools implement the semantics of a special class of buffers and may ship with libwsbm itself or may be driver-specific. The pools that are currently shipped with libwsbm are

  1. A TTM pool with buffers that map directly to TTM placement buffers.
  2. A slab pool that implements a suballocator within TTM placement buffers. This is useful to speed up buffer creation, destruction and mapping as well as to work around the 1 system page size granularity of TTM buffers.
  3. A malloc pool where buffers are put in malloced memory. This is useful for device drivers that don't support hardware vertex buffers but still need to provide storage for mesa's vertex buffers.
  4. A user pool that manages legacy VRAM and AGP memory in user-space. This is intended for Xorg drivers without a backing DRM memory manager.

Buffer types

There are three buffer object types within libwsbm. These are

  1. Ordinary buffer objects: These buffer objects may change storage as a result of the wsbmBOData and wsbmBOSubData call. The intention is to aid driver developers to implement the semantics of wsbmBOData and wsbmBOSubData in a multi-context environment where more than one context may reference the same buffer objects, and implementation may be tricky.
  2. Simple buffer objects: These buffer object never change storage. It's invalide to call wsbmBOData and wsbmBOSubData on simple buffer objects:
  3. Reference buffer objects: These are in essence simple buffer objects that are shared and created by another application, for example shared front buffers. It's illegal to call wsbmBOData on such buffers.

Location

The libwsbm library lives in git+ssh://git.freedesktop.org/git/mesa/libwsbm

Build requirements

Some of the buffer pools shipped with libwsbm depend on a TTM-enabled version of libdrm, so you need to have libdrm installed. You also need pthreads.