Crate drmkit_planes

Expand description

Display-plane capabilities, the layer model, and the plane allocator.

Port of src/planes/ from drm-cxx @ dc2915b.

Three pieces, bottom-up:

PlaneCapabilities and PlaneRegistry — what each plane on a device can do: which CRTCs it feeds, which formats and modifiers it scans out, whether it rotates, where its zpos may sit. Built from a device behind the device feature, or from fixtures a caller supplies, which is what lets the allocator be tested against hardware nobody has.
Layer — one thing to put on screen, as a bag of KMS properties plus the hints that inform placement.
Allocator — which layer goes on which plane.

§Why placement is a search

Nothing in the kernel’s uAPI answers “can these layers be scanned out together”. IN_FORMATS prunes, possible_crtcs prunes, and neither settles it: bandwidth limits, scaler counts and per-driver rules decide the rest and are not advertised anywhere. The only oracle is an atomic TEST_ONLY commit, which costs an ioctl.

So the allocator proposes and the kernel disposes, and the whole design is about proposing well enough that few proposals are needed. It seeds with a maximum bipartite matching, orders candidates by a score, backtracks by dropping the layer it can most afford to composite, and spends at most Allocator::DEFAULT_MAX_TEST_COMMITS test commits per search before settling for what it has. Layers that do not overlap are solved independently, so a busy corner of the screen does not make the rest of it expensive.

Two caches keep the steady state near zero ioctls: a warm start that re-validates last frame’s assignment, and the fast path below.

§Invariant 4

Layer::property_hash isolates content from placement: a frame that changes only content on already-placed layers reuses the cached plane assignment and skips the redundant TEST_ONLY commit.

The C++ can only document which properties are which. Here the split is PropTag::class, an exhaustive match, so a property added without a classification does not compile — the misclassification the invariant warns about cannot reach a running system.

Structs§

Allocation: The result of one allocation pass.
Allocator: Assigns layers to display planes.
AlwaysAccept: A committer that accepts everything. For tests that care about which assignment the search proposes rather than how it narrows one down.
BipartiteMatching: A reusable Hopcroft–Karp matcher.
BlendModeValues: Driver-assigned enum integers for a property’s named values.
ColorEncodingValues: Driver-assigned enum integers for COLOR_ENCODING.
ColorPipeline: Per-plane color pipeline support (pre-blend CMS).
ColorRangeValues: Driver-assigned enum integers for COLOR_RANGE.
Diagnostics: What one allocation pass did.
Layer: One layer the scene wants on screen.
LayerId: Stable identity for a layer across frames.
LayerRef: One layer offered to the allocator.
Output: The layers destined for one CRTC, in presentation order.
PlaneAssignment: Plane-to-layer assignment.
PlaneCapabilities: Everything the allocator needs to know about one plane.
PlaneRegistry: Every display plane the device exposes.
PropertySnapshot: A snapshot of a layer’s property state, for diffing against the last commit.
Rect: An axis-aligned rectangle in CRTC pixels.
ScoreContext: Everything score_pair needs that is not the plane or the layer.
StackEntry: One armed plane in a frame’s stack.
TestCache: Memoized test-commit verdicts, keyed by (plane, property_hash).

Enums§

ColorEncoding: Plane COLOR_ENCODING: the YCbCr-to-RGB matrix applied when scanning out a YUV format. Ignored by the kernel for RGB.
ColorRange: Plane COLOR_RANGE: whether 8-bit YCbCr is full-range (0..255) or limited-range (16..235 luma, 16..240 chroma).
ContentType: What a layer is showing, for placement priority.
PlaneType: The kernel’s plane type.
PropClass: What a property describes, for the FB-only fast path.
PropTag: Property tags a layer recognizes.
TestFailure: Why a test commit was rejected.

Constants§

NUM_PROPS: Number of distinct property tags.
WARM_STABILITY_BONUS: The bonus for keeping a layer on the plane it held last frame.

Traits§

TestCommitter: Validates tentative plane assignments.

Functions§

bandwidth_class_bonus: Power-aware placement bonus for a buffer’s bandwidth class.
cost_bias: Bounded tiebreak by a layer’s per-frame scanout byte cost.
effective_zpos: Where a layer requesting layer_zpos stacks on plane: the fixed slot, else the layer’s own written zpos. None when neither is known.
keep_priority: Keep-or-drop ordering under plane pressure.
layer_priority: Content-class placement priority.
layers_intersect: Whether two layers overlap on the CRTC.
multirect_pairing_ok: Whether a plane whose multirect parent is parent may be placed, given the planes already in use: a plain plane always, a virtual one only once its parent is in use. in_use(id) reports whether a plane id is taken.
parse_blend_stage_limit: How many planes a CRTC can stack, from its capabilities blob, or None when the blob does not say.
parse_multirect_parent: The parent plane id from a capabilities blob’s text, or None when the blob does not mark the plane as a multirect rectangle, or the value is garbage.
plane_statically_compatible: Whether a plane could possibly scan out a layer.
rects_intersect: Whether two destination rectangles overlap.
rescale_alpha: Map a 16-bit layer alpha onto the range a plane advertises.
score_pair: Score a candidate placement. Higher is more preferred.
split_independent_groups: Partition layer indices into spatially independent groups.
stack_zpos: Number the armed planes’ zpos densely, in requested order.
stacked_zpos: The zpos to write on each armed plane, as (plane_id, value).
stacked_zpos_beneath: stacked_zpos with beneath stacked under the planes requesting the same zpos: the composition canvas in the slot Allocator::canvas_zpos gives it.
stacking_consistent: Whether layer A (zpos za) on pa and layer B (zpos zb) on pb stack in the order their zpos values request.
stacks_by_plane_id: Whether the planes on crtc_index stack by plane id: no non-cursor plane exposes zpos.
zpos_fixed: Whether the plane’s zpos is a single fixed slot that cannot be written.