| What are these headers ? | |
| ------------------------ | |
| This is the canonical source of drm headers that user space should use for | |
| communicating with the kernel DRM subsystem. | |
| They flow from the kernel, thus any changes must be merged there first. | |
| Do _not_ attempt to "fix" these by deviating from the kernel ones ! | |
| Non-linux platforms - changes/patches | |
| ------------------------------------- | |
| If your platform has local changes, please send them upstream for inclusion. | |
| Even if your patches don't get accepted in their current form, devs will | |
| give you feedback on how to address things properly. | |
| git send-email --subject-prefix="PATCH libdrm" your patches to dri-devel | |
| mailing list. | |
| Before doing so, please consider the following: | |
| - Have the [libdrm vs kernel] headers on your platform deviated ? | |
| Consider unifying them first. | |
| - Have you introduced additional ABI that's not available in Linux ? | |
| Propose it for [Linux kernel] upstream inclusion. | |
| If that doesn't work out (hopefully it never does), move it to another header | |
| and/or keep the change(s) local ? | |
| - Are your changes DRI1/UMS specific ? | |
| There is virtually no interest/power in keeping those legacy interfaces. They | |
| are around due to the kernel "thou shalt not break existing user space" rule. | |
| Consider porting the driver to DRI2/KMS - all (almost?) sensible hardware is | |
| capable of supporting those. | |
| Which headers go where ? | |
| ------------------------ | |
| A snipped from the, now removed, Makefile.am used to state: | |
| XXX airlied says, nothing besides *_drm.h and drm*.h should be necessary. | |
| however, r300 and via need their reg headers installed in order to build. | |
| better solutions are welcome. | |
| Obviously the r300 and via headers are no longer around ;-) | |
| Reason behind is that the drm headers can be used as a basic communications | |
| channel with the respective kernel modules. If more advanced functionality is | |
| required one can pull the specific libdrm_$driver which is free to pull | |
| additional files from the kernel. | |
| For example: nouveau has nouveau/nvif/*.h while vc4 has vc4/*.h | |
| If your driver is still in prototyping/staging state, consider moving the | |
| $driver_drm.h into $driver and _not_ installing it. An header providing opaque | |
| definitions and access [via $driver_drmif.h or similar] would be better fit. | |
| When and which headers to update | |
| -------------------------------- | |
| Ideally all files will be synced (updated) with the latest released kernel on | |
| each libdrm release. Sadly that's not yet possible since quite a few headers | |
| differ significantly - see Outdated or Broken Headers section below. | |
| That said, it's up-to the individual developers to sync with newer version | |
| (from drm-next) as they see fit. | |
| When and how to update these files | |
| ---------------------------------- | |
| Note: One should not do _any_ changes to the files apart from the steps below. | |
| In order to update the files do the following: | |
| - Switch to a Linux kernel tree/branch which is not rebased. | |
| For example: airlied/drm-next | |
| - Install the headers via `make headers_install' to a separate location. | |
| - Copy the drm header[s] + git add + git commit. | |
| - Note: Your commit message must include: | |
| a) Brief summary on the delta. If there's any change that looks like an | |
| API/ABI break one _must_ explicitly state why it's safe to do so. | |
| b) "Generated using make headers_install." | |
| c) "Generated from $tree/branch commit $sha" | |
| Outdated or Broken Headers | |
| -------------------------- | |
| This section contains a list of headers and the respective "issues" they might | |
| have relative to their kernel equivalent. | |
| Nearly all headers: | |
| - Missing extern C notation. | |
| Status: Trivial. | |
| Most UMS headers: | |
| - Not using fixed size integers - compat ioctls are broken. | |
| Status: ? | |
| Promote to fixed size ints, which match the current (32bit) ones. | |
| drm_mode.h | |
| - Missing DPI encode/connector pair. | |
| Status: Trivial. | |
| i915_drm.h | |
| - Missing PARAMS - HAS_POOLED_EU, MIN_EU_IN_POOL CONTEXT_PARAM_NO_ERROR_CAPTURE | |
| Status: Trivial. | |
| mga_drm.h | |
| - Typo fix, use struct over typedef. | |
| Status: Trivial. | |
| nouveau_drm.h | |
| - Missing macros NOUVEAU_GETPARAM*, NOUVEAU_DRM_HEADER_PATCHLEVEL, structs, | |
| enums, using stdint.h over the __u* types. | |
| Status: ? | |
| qxl_drm.h | |
| - Using the stdint.h uint*_t over the respective __u* ones | |
| Status: Trivial. | |
| r128_drm.h | |
| - Broken compat ioctls. | |
| radeon_drm.h | |
| - Missing RADEON_TILING_R600_NO_SCANOUT, CIK_TILE_MODE_*, broken UMS ioctls, | |
| using stdint types. | |
| - Both kernel and libdrm: missing padding - | |
| drm_radeon_gem_{create,{g,s}et_tiling,set_domain} others ? | |
| Status: ? | |
| savage_drm.h | |
| - Renamed ioctls - DRM_IOCTL_SAVAGE_{,BCI}_EVENT_EMIT, compat ioctls are broken. | |
| Status: ? | |
| sis_drm.h | |
| - Borken ioctls + libdrm uses int vs kernel long | |
| Status: ? | |
| via_drm.h | |
| - Borken ioctls - libdrm int vs kernel long | |
| Status: ? | |
| omap_drm.h (living in $TOP/omap) | |
| - License mismatch, missing DRM_IOCTL_OMAP_GEM_NEW and related struct | |
| Status: ? | |
| msm_drm.h (located in $TOP/freedreno/msm/) | |
| - License mismatch, missing MSM_PIPE_*, MSM_SUBMIT_*. Renamed | |
| drm_msm_gem_submit::flags, missing drm_msm_gem_submit::fence_fd. | |
| Status: ? | |
| exynos_drm.h (living in $TOP/exynos) | |
| - License mismatch, now using fixed size ints (but not everywhere). Lots of | |
| new stuff. | |
| Status: ? |